@zenera/cli 1.1.28 → 1.1.29

package/dist/commands/key.js

@@ -1,10 +1,11 @@
+import { GATEWAY_URL_ENV } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { parse } from "../args.js";
 import { ensureHome } from "../home.js";
-import { ambient, ambientId, assertNotEmpty, checkRegion, describe, envNames, envOf, formOf, keyId, KeyStore, mask, OWNERS, parseRef, SHAPES, } from "../keys.js";
+import { ambient, ambientId, assertNotEmpty, checkRegion, describe, envNames, envOf, formOf, GATEWAYS, isGateway, keyId, KeyStore, mask, MODES, OWNERS, parseRef, SHAPES, } from "../keys.js";
 import { probe, probeAll } from "../liveness.js";
-import { ago, ask, askSecret, bold, confirm, credentialError, cyan, dim, green, isInteractive, json, note, progress, readStdin, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen key <ls|add|use|check|rm|show|env> [ref] [options]';
+import { ago, ask, askSecret, badge, bold, confirm, credentialError, cyan, dim, green, isInteractive, json, note, progress, readStdin, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen key <ls|add|use|mode|check|rm|show|env> [ref] [options]';
 // ---------------------------------------------------------------------------
 // Display
 // ---------------------------------------------------------------------------
@@ -32,6 +33,9 @@ const ORIGIN = {
  * the environment supplied either, because then the stored one is not in play.
  */
 function placed(store, entry) {
+    if (entry.url) {
+        return dim(entry.url);
+    }
     if (entry.provider !== 'vertex' || entry.holds !== 'file') {
         return '';
     }
@@ -61,14 +65,28 @@ function asEntry(cred) {
 }
 function rows(store, borrowed) {
     const out = [
-        [bold(''), bold('KEY'), bold('VALUE'), bold('GCP'), bold('STATE'), bold('CHECKED')],
+        [bold(''), bold('KEY'), bold('VALUE'), bold('WHERE'), bold('STATE'), bold('CHECKED')],
     ];
     for (const provider of OWNERS) {
+        // Held but not in play under the current mode: drawn grey, so the live set stands out.
+        const idle = unused(store, provider);
         for (const entry of store.for(provider)) {
             const shadow = envNames(provider).find((name) => process.env[name]);
+            if (idle) {
+                out.push([
+                    dim('-'),
+                    dim(keyId(entry)),
+                    dim(describe(store, entry)),
+                    dim(entry.url ?? ''),
+                    dim(entry.check?.state ?? 'unchecked'),
+                    dim(`not used in ${store.mode} mode`),
+                ]);
+                continue;
+            }
+            const gateway = isGateway(provider);
             out.push([
                 store.isActive(entry) ? green('*') : ' ',
-                keyId(entry),
+                gateway && store.isActive(entry) ? bold(cyan(keyId(entry))) : keyId(entry),
                 dim(describe(store, entry)),
                 placed(store, entry),
                 state(entry),
@@ -78,17 +96,47 @@ function rows(store, borrowed) {
         }
         for (const [cred, entry] of borrowed.filter(([c]) => c.provider === provider)) {
             out.push([
-                dim('~'),
+                dim(idle ? '-' : '~'),
                 dim(ambientId(cred)),
                 dim(describe(store, entry)),
-                placed(store, entry),
-                state(entry),
-                dim(cred.env ? 'from the environment' : 'from gcloud'),
+                idle ? '' : placed(store, entry),
+                idle ? dim(entry.check?.state ?? 'unchecked') : state(entry),
+                dim(idle
+                    ? `not used in ${store.mode} mode`
+                    : cred.env
+                        ? 'from the environment'
+                        : 'from gcloud'),
             ]);
         }
     }
     return table(out);
 }
+/** A vendor key under a gateway mode, or a gateway key under any other. */
+function unused(store, provider) {
+    if (isGateway(provider)) {
+        return store.mode !== provider;
+    }
+    return SHAPES[provider].kind === 'model' && store.mode !== 'direct';
+}
+/**
+ * Above the table, because it decides which half of the table matters. Said
+ * only once a gateway key exists: before that there is no choice to report.
+ */
+function modeLine(store) {
+    const mode = store.mode;
+    if (mode === 'direct') {
+        if (GATEWAYS.some((g) => store.active(g))) {
+            note(`${bold('mode')} ${cyan('direct')} ${dim('— each provider with its own key; zen key mode bifrost to send every model through the gateway')}`);
+            note('');
+        }
+        return;
+    }
+    const gateway = store.active(mode);
+    note(`${cyan(badge(`⇄ ${mode.toUpperCase()} MODE`))} ${bold(gateway?.url ?? 'no url stored')}`);
+    note(dim(`every model goes through the gateway with ${gateway ? keyId(gateway) : 'no key'}; ` +
+        'vendor keys are not used — zen key mode direct to stop'));
+    note('');
+}
 /**
  * Checking is a network round trip per key, so it says which ones have come
  * back. Silence for ten seconds is indistinguishable from a hang.
@@ -123,6 +171,7 @@ const ls = async (ctx, args) => {
     }
     if (ctx.json) {
         json({
+            mode: store.mode,
             keys: store.entries.map((e) => ({
                 ...e,
                 value: e.holds === 'file' ? store.fileOf(e) : mask(e.value),
@@ -145,8 +194,12 @@ const ls = async (ctx, args) => {
         note(dim('add one: zen key add openai'));
         return;
     }
+    modeLine(store);
     writeAll(rows(store, borrowed));
-    const missing = OWNERS.filter((p) => !store.active(p) && !borrowed.some(([c]) => c.provider === p));
+    const missing = OWNERS.filter((p) => !store.active(p) &&
+        !borrowed.some(([c]) => c.provider === p) &&
+        (!isGateway(p) || store.mode === p) &&
+        (store.mode === 'direct' || SHAPES[p].kind !== 'model'));
     if (missing.length) {
         note('');
         note(dim(`no key for: ${missing.join(', ')}`));
@@ -164,8 +217,9 @@ const add = async (ctx, args) => {
         // Prefixed because every other command's --project is a Zenera one.
         'gcp-project': { type: 'string' },
         'gcp-location': { type: 'string' },
+        url: { type: 'string' },
     }, 'zen key add <provider>[/name] [--name <name>] [--gcp-project <id>] ' +
-        '[--gcp-location <region>] [--no-check]');
+        '[--gcp-location <region>] [--url <gateway url>] [--no-check]');
     const ref = positionals[0];
     if (!ref) {
         throw usageError('which provider?', `one of: ${OWNERS.join(', ')}`);
@@ -177,6 +231,7 @@ const add = async (ctx, args) => {
     if ((values['gcp-project'] || values['gcp-location']) && provider !== 'vertex') {
         throw usageError(`--gcp-project and --gcp-location mean nothing to ${shape.label}`, 'they configure a Vertex service account');
     }
+    const url = gatewayUrl(provider, values.url);
     // Checked before the prompt, so a typo does not cost you pasting the key.
     const region = values['gcp-location'];
     if (region !== undefined && !checkRegion(region)) {
@@ -208,6 +263,7 @@ const add = async (ctx, args) => {
     const entry = store.add(provider, name, raw, {
         project: values['gcp-project'],
         location: values['gcp-location'],
+        url,
     });
     // Verified before it is trusted, but stored either way: a key that cannot
     // be checked right now — offline, behind a proxy — is not a key that is
@@ -249,6 +305,9 @@ const add = async (ctx, args) => {
     if (process.env[envOf(entry)]) {
         note(yellow(`$${envOf(entry)} is set and will win over this`));
     }
+    if (isGateway(provider) && store.mode !== provider) {
+        note(dim(`not in use yet — send every model through it with: zen key mode ${provider}`));
+    }
     if (provider === 'vertex' && entry.holds === 'file' && !entry.project) {
         const found = store.projectOf(entry);
         note(dim(found
@@ -256,6 +315,36 @@ const add = async (ctx, args) => {
             : 'no --gcp-project given, and the key file names no project_id'));
     }
 };
+/**
+ * A gateway is nothing without its address, and nothing else has one. Only
+ * http(s) is taken: the url ends up as an SDK base url, where anything else
+ * fails three frames down.
+ */
+function gatewayUrl(provider, raw) {
+    if (!isGateway(provider)) {
+        if (raw !== undefined) {
+            throw usageError(`--url means nothing to ${SHAPES[provider].label}`, 'it locates a gateway');
+        }
+        return undefined;
+    }
+    if (!raw) {
+        throw usageError(`${SHAPES[provider].label} needs --url`, `e.g. zen key add ${provider} --url https://bifrost.example.com`);
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw usageError(`"${raw}" is not a url`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw usageError(`"${raw}" is not an http(s) url`);
+    }
+    if (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+        note(yellow('plain http: the virtual key will cross the network unencrypted'));
+    }
+    return url.href.replace(/\/+$/, '');
+}
 /**
  * A provider with two forms cannot ask for one of them. It asks with the echo
  * off, because one of the two answers is a secret and there is no way to know
@@ -294,6 +383,31 @@ const use = async (ctx, args) => {
     }
     note(`${green('using')} ${bold(keyId(entry))} for ${SHAPES[provider].label}`);
 };
+/** Bare, it says which mode a run would use; with a word, it switches. */
+const mode = async (ctx, args) => {
+    const { positionals } = parse(args, {}, `zen key mode [${MODES.join('|')}]`);
+    const wanted = positionals[0];
+    const store = await KeyStore.open();
+    if (wanted !== undefined) {
+        if (!MODES.includes(wanted)) {
+            throw usageError(`unknown mode "${wanted}"`, `one of: ${MODES.join(', ')}`);
+        }
+        store.setMode(wanted);
+        store.save();
+    }
+    const now = store.mode;
+    const gateway = now === 'direct' ? undefined : store.active(now);
+    if (ctx.json) {
+        json({ mode: now, ...(gateway ? { key: keyId(gateway), url: gateway.url } : {}) });
+        return;
+    }
+    if (!gateway) {
+        note(`${cyan('direct')} ${dim('— each provider is called with its own key')}`);
+        return;
+    }
+    note(`${cyan(now)} ${dim('— every model goes through')} ${gateway.url} ` +
+        dim(`with ${keyId(gateway)}`));
+};
 const check = async (ctx, args) => {
     const { positionals } = parse(args, {}, 'zen key check [provider[/name]]');
     const store = await KeyStore.open();
@@ -404,6 +518,7 @@ const show = async (ctx, args) => {
             ? [[dim('gcp project'), `${project.id} ${dim(ORIGIN[project.from])}`]]
             : []),
         ...(entry.location ? [[dim('gcp location'), entry.location]] : []),
+        ...(entry.url ? [[dim('url'), entry.url]] : []),
         [dim('state'), state(entry)],
         ...(entry.check?.fix ? [[dim('fix'), entry.check.fix]] : []),
         [dim('added'), ago(entry.addedAt)],
@@ -424,11 +539,18 @@ const env = async (ctx, args) => {
     // Ignore what is already exported: the point is to produce the exports.
     const vars = {};
     for (const provider of only ?? OWNERS) {
+        // Unasked-for, a gateway is exported only in its own mode, where it is the switch.
+        if (!only && isGateway(provider) && store.mode !== provider) {
+            continue;
+        }
         const entry = store.active(provider);
         if (!entry) {
             continue;
         }
         vars[envOf(entry)] = store.reveal(entry);
+        if (entry.url) {
+            vars[GATEWAY_URL_ENV] = entry.url;
+        }
         // A service account says which project it belongs to but not which
         // region to call, and a shell that has the file and not the region is
         // still a shell that cannot reach a model.
@@ -498,6 +620,7 @@ const SUBS = {
     list: ls,
     add,
     use,
+    mode,
     check,
     rm,
     remove: rm,
@@ -516,14 +639,22 @@ export const key = {
         '',
         'Model providers: openai, anthropic, google, vertex, openrouter.',
         'Services the tools call: exa.',
+        `Gateways every model can go through: ${GATEWAYS.join(', ')}.`,
         '',
         'Vertex takes either shape: a service-account JSON file, which wants',
         '--gcp-project and --gcp-location too, or an express-mode API key, which',
         'wants neither. Which one you gave is read off the value.',
         '',
+        'A gateway holds one virtual key and its --url. In its mode every model',
+        'goes through it, each in its own vendor protocol, and agents.yaml does',
+        'not change: vertex:gemini-3.5-flash reaches <url>/genai as',
+        'vertex/gemini-3.5-flash. Vendor keys are withheld from runs meanwhile.',
+        '',
         '  zen key ls [--check]              Everything stored, and its state.',
         '  zen key add <provider>[/name]     Read a key from stdin, or ask for it.',
+        '  zen key add bifrost --url <url>   A gateway key, and where the gateway is.',
         '  zen key use <provider>/<name>     Choose which one a run uses.',
+        '  zen key mode [direct|bifrost]     Call vendors directly, or via the gateway.',
         '  zen key check [provider[/name]]   Ask the provider whether it still works.',
         '  zen key rm <provider>/<name>      Forget one.',
         '  zen key show <ref> [--reveal]     Masked by default.',

package/dist/commands/meta.d.ts

@@ -1,3 +1,6 @@
+import { type Candidate } from '../candidates.ts';
 import type { Command } from '../command.ts';
 export declare const meta: Command;
+/** `args` is what came after `meta`, without the word being completed. */
+export declare function completeMeta(args: readonly string[], cur: string, cwd: string): Promise<Candidate[]>;
 //# sourceMappingURL=meta.d.ts.map

package/dist/commands/meta.js

@@ -5,10 +5,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parse } from "../args.js";
+import { matching, projectNames } from "../candidates.js";
 import { loadProjectEnv } from "../env.js";
 import { copilotEventLog } from "../eventlog.js";
 import { ensureHome } from "../home.js";
-import { assertOwner, KeyStore, PROVIDERS } from "../keys.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 { splitRef } from "../modelref.js";
@@ -57,6 +58,32 @@ function page(p) {
         write(line ? `  ${line}` : '');
     }
 }
+/** Kept apart from `run` so that shell completion offers exactly what is parsed. */
+const OPTIONS = {
+    project: { type: 'string' },
+    provider: { type: 'string' },
+    model: { type: 'string' },
+    prompt: { type: 'string', short: 'p' },
+    'prompt-file': { type: 'string' },
+    agent: { type: 'string' },
+    effort: { type: 'string' },
+    share: { type: 'string' },
+    events: { type: 'string' },
+    resume: { type: 'string' },
+    continue: { type: 'boolean' },
+    'session-id': { type: 'string' },
+    retries: { type: 'string' },
+    'allow-all': { type: 'boolean' },
+    'allow-tool': { type: 'string' },
+    ask: { type: 'boolean' },
+    'add-dir': { type: 'string', multiple: true },
+    'dry-run': { type: 'boolean' },
+    local: { type: 'boolean' },
+    pick: { type: 'boolean' },
+    clear: { type: 'boolean' },
+    force: { type: 'boolean' },
+    'no-refresh': { type: 'boolean' },
+};
 const RUN_FORMS = [
     '  zen meta run [project] "<question>"      ask it something',
     '  zen meta run [project] /<name> [words]   run a stored prompt',
@@ -65,7 +92,8 @@ const RUN_FORMS = [
 const RUN_ARGUMENTS = [
     'Arguments:',
     '  [project]   Name of a project. Default: the one you are in.',
-    '  [prompt]    Your question, in quotes. Also --prompt, or piped in.',
+    '  [prompt]    Your question, in quotes. Or --prompt, or piped in when neither',
+    '              it nor --prompt-file is given.',
     '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
     '  [words]     Appended to that prompt as a final line.',
 ];
@@ -74,7 +102,10 @@ const RUN_OPTIONS = [
     '  --project <name|dir>   Which project to work in. The agent is rooted there.',
     '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
     '  --provider <name>      Force the key to use. Default: the model ref says.',
-    '  --prompt-file <file>   Append this file to the prompt, after any words.',
+    '  -p, --prompt <text>    The question, in place of [prompt].',
+    '                         Ignored with /<name>: put words after it instead.',
+    '  --prompt-file <file>   Added after the question - or after /<name> and its',
+    '                         words - past a blank line. Alone, it is the question.',
     '  --agent <name>         A .github/agents/<name>.agent.md.',
     '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
     '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
@@ -182,31 +213,7 @@ export const meta = {
             });
             return await run({ args, json: ctx.json, cwd: ctx.cwd }, found);
         }
-        const { values, positionals } = parse(ctx.args, {
-            project: { type: 'string' },
-            provider: { type: 'string' },
-            model: { type: 'string' },
-            prompt: { type: 'string', short: 'p' },
-            'prompt-file': { type: 'string' },
-            agent: { type: 'string' },
-            effort: { type: 'string' },
-            share: { type: 'string' },
-            events: { type: 'string' },
-            resume: { type: 'string' },
-            continue: { type: 'boolean' },
-            'session-id': { type: 'string' },
-            retries: { type: 'string' },
-            'allow-all': { type: 'boolean' },
-            'allow-tool': { type: 'string' },
-            ask: { type: 'boolean' },
-            'add-dir': { type: 'string', multiple: true },
-            'dry-run': { type: 'boolean' },
-            local: { type: 'boolean' },
-            pick: { type: 'boolean' },
-            clear: { type: 'boolean' },
-            force: { type: 'boolean' },
-            'no-refresh': { type: 'boolean' },
-        }, USAGE);
+        const { values, positionals } = parse(ctx.args, OPTIONS, USAGE);
         // `zen meta acme run` is typed at least as often as `zen meta run acme`,
         // and read literally it asks the agent the one-word question "run" —
         // a whole model call spent on a typo, with nothing on screen to say so.
@@ -388,6 +395,104 @@ async function pickPrompt(ctx, project) {
     return await choose('Which prompt?', names.map((n) => ({ label: `/${n}`, value: n })));
 }
 // ---------------------------------------------------------------------------
+// Completing it
+//
+// `zen meta run acme /<Tab>` is where a terminal can show what an editor's menu
+// shows. It reads the line the way `stored` does — a leading slash is a prompt,
+// a bare word that names a project is the project — and it only ever reads:
+// the editor files are not refreshed for the sake of a Tab.
+// ---------------------------------------------------------------------------
+async function findProject(name) {
+    try {
+        return await Projects.find(name);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function promptsOf(project) {
+    if (!project) {
+        return [];
+    }
+    const names = await listPrompts(project.dir);
+    return await Promise.all(names.map(async (name) => ({
+        value: `/${name}`,
+        description: (await loadPrompt(project.dir, name).catch(() => undefined))?.description,
+    })));
+}
+/** `args` is what came after `meta`, without the word being completed. */
+export async function completeMeta(args, cur, cwd) {
+    const words = [];
+    let flagged;
+    let waiting;
+    for (const arg of args) {
+        if (waiting) {
+            if (waiting === 'project') {
+                flagged = arg;
+            }
+            waiting = undefined;
+        }
+        else if (arg.startsWith('--')) {
+            const [flag, value] = arg.slice(2).split(/=(.*)/s);
+            if (value !== undefined) {
+                flagged = flag === 'project' ? value : flagged;
+            }
+            else if (OPTIONS[flag]?.type === 'string') {
+                waiting = flag;
+            }
+        }
+        else if (arg === '-p') {
+            waiting = 'prompt';
+        }
+        else if (!arg.startsWith('-')) {
+            words.push(arg);
+        }
+    }
+    // A flag's value is the flag's to name, and most of them are free text or a
+    // path — which is the shell's.
+    if (waiting === 'provider') {
+        return matching(PROVIDERS.map((value) => ({ value })), cur);
+    }
+    if (waiting === 'project') {
+        return matching(await projectNames(), cur);
+    }
+    if (waiting) {
+        return [];
+    }
+    const at = words.findIndex((w) => VERBS.has(w));
+    const named = at === 1 ? words[0] : undefined;
+    const verb = at === 0 || (named && (await findProject(named))) ? words[at] : undefined;
+    if (cur.startsWith('-')) {
+        return verb === 'dataset' || verb === 'finetune'
+            ? []
+            : matching(Object.keys(OPTIONS).map((flag) => ({ value: `--${flag}` })), cur);
+    }
+    if (!verb) {
+        const verbs = [...VERBS].map((value) => ({ value }));
+        if (words.length === 0) {
+            return matching([...verbs, ...(await projectNames())], cur);
+        }
+        return words.length === 1 && (await findProject(words[0])) ? matching(verbs, cur) : [];
+    }
+    const rest = words.slice(at + 1);
+    if (verb === 'prompts' || verb === 'resume') {
+        return flagged || named || rest.length > 0 ? [] : matching(await projectNames(), cur);
+    }
+    if (verb !== 'run' || rest.some((w) => w.startsWith('/'))) {
+        // Past the prompt's name, what follows is files and words.
+        return [];
+    }
+    const given = flagged ?? named ?? rest[0];
+    if (given === undefined) {
+        const here = await Projects.current(cwd).catch(() => undefined);
+        return matching([...(await promptsOf(here)), ...(await projectNames())], cur);
+    }
+    const project = await findProject(given);
+    const fromRest = !flagged && !named;
+    const free = rest.length - (fromRest && project ? 1 : 0);
+    return free > 0 ? [] : matching(await promptsOf(project), cur);
+}
+// ---------------------------------------------------------------------------
 // zen meta prompts [project]
 //
 // A slash command is only discoverable inside an editor, where a menu drops
@@ -789,7 +894,7 @@ function count(text, flag) {
 }
 function asProvider(name) {
     const owner = assertOwner(name);
-    if (owner === 'exa') {
+    if (!isProvider(owner)) {
         throw usageError(`${name} is not a model provider`);
     }
     return owner;