@zenera/cli 1.1.28 → 1.1.30

package/dist/commands/models.js

@@ -7,18 +7,18 @@
 // This command answers the first, and needs no project at all.
 //
 // The split matters most when something breaks. `zen check` says "this
-// embedder was refused"; `zen models pick --embedding` says "use this one
-// instead", and prints a ref on stdout that can be pasted straight back into
-// agents.yaml — or read by an agent doing the pasting.
+// embedder was refused"; `zen models ls --embeddings` and `zen models test`
+// find one that answers, as a ref that can be pasted straight back into
+// agents.yaml.
 // ---------------------------------------------------------------------------
-import { createEmbedder, ModelRegistry } from '@zenera/neo';
+import { createEmbedder, GATEWAY_NAME, gatewayOf, ModelRegistry } from '@zenera/neo';
 import { parse } from "../args.js";
-import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, PREFERRED, routerBalance, } from "../catalog.js";
+import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, routerBalance, } from "../catalog.js";
 import { ensureHome } from "../home.js";
 import { envNames, form, isProvider, KeyStore, PROVIDERS } from "../keys.js";
 import { probeChat, probeModel } from "../liveness.js";
 import { ago, bold, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen models <providers|ls|search|show|test|pick|browse> [ref] [options]';
+const USAGE = 'zen models <providers|ls|search|show|test|browse> [ref] [options]';
 /**
  * The keyring is materialised here, and only here.
  *
@@ -33,6 +33,10 @@ async function credentials() {
     // difference between "the environment had it" and "the keyring supplied it".
     const fromEnv = new Set(PROVIDERS.filter((p) => envNames(p).some((n) => process.env[n])));
     store.materialize();
+    const gateway = gatewayOf();
+    if (gateway) {
+        return { store, fromEnv, usable: [...PROVIDERS], gateway };
+    }
     const usable = [
         ...PROVIDERS.filter((p) => fromEnv.has(p)),
         ...PROVIDERS.filter((p) => !fromEnv.has(p) && Boolean(store.active(p))),
@@ -40,6 +44,9 @@ async function credentials() {
     return { store, fromEnv, usable };
 }
 function source(where, provider) {
+    if (where.gateway) {
+        return GATEWAY_NAME;
+    }
     if (where.fromEnv.has(provider)) {
         return 'environment';
     }
@@ -101,10 +108,22 @@ const tokens = (n) => {
     }
     return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
 };
+/**
+ * Said before any listing in a gateway mode, on stderr: the same command lists
+ * something else entirely there, and nothing in a row of model ids shows it.
+ */
+function announce(ctx, where) {
+    if (!where.gateway || ctx.json) {
+        return;
+    }
+    note(`${cyan(`⇄ ${GATEWAY_NAME} mode`)} ${dim('only what')} ${where.gateway.baseURL} ` +
+        dim('serves; zen key mode direct to list the vendors'));
+    note('');
+}
 /** Freshness of a listing, said the way a person would ask about it. */
 function freshness(cat) {
     if (cat.origin === 'curated') {
-        return yellow('built-in list');
+        return cat.via ? yellow('not listed yet') : yellow('built-in list');
     }
     if (cat.origin === 'stale') {
         return yellow(`stale, ${ago(cat.fetchedAt)}`);
@@ -163,8 +182,9 @@ function explain(cats) {
 const providers = async (ctx, args) => {
     const { values } = parse(args, { refresh: { type: 'boolean' } }, 'zen models providers [--refresh]');
     const where = await credentials();
+    // A gateway lists every provider in one request, so its overview can afford to ask.
     const cats = await loadCatalogs(PROVIDERS, {
-        offline: !values.refresh,
+        offline: !values.refresh && !where.gateway,
         refresh: values.refresh,
     });
     const by = new Map(cats.map((c) => [c.provider, c]));
@@ -176,9 +196,11 @@ const providers = async (ctx, args) => {
             models: by.get(p)?.entries.length ?? 0,
             origin: by.get(p)?.origin,
             fetchedAt: by.get(p)?.fetchedAt,
+            ...(where.gateway ? { gateway: where.gateway.baseURL } : {}),
         })));
         return;
     }
+    announce(ctx, where);
     writeAll(table(PROVIDERS.map((p) => {
         const cat = by.get(p);
         const cred = source(where, p);
@@ -193,7 +215,6 @@ const providers = async (ctx, args) => {
     note('');
     note(dim('zen models ls <provider>   what one of them serves'));
     note(dim('zen models browse          walk them with the arrow keys'));
-    note(dim('zen models pick --chat     the first one that answers'));
 };
 // ---------------------------------------------------------------------------
 // ls
@@ -225,9 +246,11 @@ const ls = async (ctx, args) => {
                 origin,
                 fetchedAt,
             })),
+            ...(where.gateway ? { gateway: where.gateway.baseURL } : {}),
         });
         return;
     }
+    announce(ctx, where);
     explain(cats);
     if (all.length === 0) {
         note(dim('nothing matched — try: zen models ls --refresh'));
@@ -237,7 +260,7 @@ const ls = async (ctx, args) => {
     if (all.length > limit) {
         note(dim(`${all.length - limit} more — narrow with \`zen models search\`, or pass --all`));
     }
-    if (all.some(isPartner)) {
+    if (!where.gateway && all.some(isPartner)) {
         note(dim('partner models are billed through Vertex and must be enabled in Model Garden first: https://console.cloud.google.com/vertex-ai/model-garden'));
     }
 };
@@ -281,6 +304,7 @@ const search = async (ctx, args) => {
         json({ query, matched: hits.length, models: hits.slice(0, limit) });
         return;
     }
+    announce(ctx, where);
     explain(cats);
     if (hits.length === 0) {
         note(dim(`nothing matched "${query}" — try fewer words, or --refresh`));
@@ -322,15 +346,17 @@ const show = async (ctx, args) => {
         throw usageError('which model?', 'see: zen models ls');
     }
     const { provider, id } = split(ref);
+    const where = await credentials();
     const cat = await loadCatalog(provider, { refresh: values.refresh });
     const found = cat.entries.find((e) => e.id === id);
     if (ctx.json) {
         json(found ?? { ref: `${provider}:${id}`, provider, id, known: false });
         return;
     }
+    announce(ctx, where);
     explain([cat]);
     if (!found) {
-        note(`${yellow('not listed')} ${provider} does not advertise ${bold(id)}`);
+        note(`${yellow('not listed')} ${where.gateway ? GATEWAY_NAME : provider} does not advertise ${bold(id)}`);
         note(dim(`it may still work — try: zen models test ${provider}:${id}`));
         note(dim(`or look: zen models search ${id} --provider ${provider}`));
         return;
@@ -360,7 +386,11 @@ const show = async (ctx, args) => {
             ? `$${found.pricing.prompt}/token in, $${found.pricing.completion ?? '?'}/token out`
             : undefined);
     add('released', found.created);
-    add('source', found.source === 'live' ? `${provider}, ${freshness(cat)}` : 'built-in list');
+    add('source', found.source !== 'live'
+        ? 'built-in list'
+        : cat.via
+            ? `${cat.via.name} (${provider}), ${freshness(cat)}`
+            : `${provider}, ${freshness(cat)}`);
     writeAll(table(rows));
     if (found.description) {
         note('');
@@ -456,6 +486,7 @@ const test = async (ctx, args) => {
         json(probes);
     }
     else {
+        announce(ctx, where);
         writeAll(table(probes.map((p) => [
             cyan(p.ref),
             verdict(p),
@@ -469,90 +500,16 @@ const test = async (ctx, args) => {
         }
         // A Vertex refusal is about a model *in a project*, and the project is
         // the half of that nobody typed.
-        if (parsed.some((p) => p.provider === 'vertex')) {
+        if (!where.gateway && parsed.some((p) => p.provider === 'vertex')) {
             note(dim(vertexAt(where)));
         }
     }
     const failed = probes.filter((p) => p.check.state !== 'live');
     if (failed.length > 0) {
-        // The suggestion follows what was actually asked, not what was flagged:
-        // being told to `pick --chat` after an embedder was refused is how a
-        // recovery path stops being one.
-        const role = failed.every((p) => p.kind === 'embedding') ? '--embedding' : '--chat';
-        throw credentialError(`${failed.length} of ${probes.length} did not answer`, `find one that does: zen models pick ${role}`);
-    }
-};
-// ---------------------------------------------------------------------------
-// pick
-// ---------------------------------------------------------------------------
-/**
- * The recovery path, and the reason this command exists.
- *
- * Candidates are tried one at a time and the walk stops at the first that
- * answers. Sequential on purpose: the goal is *one* working ref, and firing
- * eight billable calls to find it is the wrong trade — especially for the
- * caller most likely to be running this, which is an agent that has just been
- * refused and is looking for somewhere else to go.
- */
-const pick = async (ctx, args) => {
-    const { values } = parse(args, { ...ROLE_OPTIONS, provider: { type: 'string' }, limit: { type: 'string' } }, 'zen models pick --chat|--embedding [--provider p] [--limit N]');
-    const roles = rolesFrom(values);
-    if (roles.length !== 1 || (roles[0] !== 'chat' && roles[0] !== 'embedding')) {
-        throw usageError('which kind of model?', 'pass --chat or --embedding');
-    }
-    const role = roles[0];
-    const where = await credentials();
-    const targets = scope(where, values.provider);
-    const cap = num(values.limit, '--limit') ?? 8;
-    const candidates = targets
-        .flatMap((p) => PREFERRED[p][role].map((id) => ({ provider: p, id, ref: `${p}:${id}` })))
-        .slice(0, cap);
-    if (candidates.length === 0) {
-        throw credentialError(`no ${role} model is known for ${targets.join(', ')}`, 'try: zen models pick --provider openai');
-    }
-    const tried = [];
-    const bar = ctx.json ? undefined : progress();
-    for (const candidate of candidates) {
-        bar?.update(dim(`trying ${candidate.ref} …`));
-        const probe = await probeModel(target(candidate.ref, candidate.provider, candidate.id, role));
-        tried.push(probe);
-        if (probe.check.state !== 'live') {
-            continue;
-        }
-        bar?.done();
-        if (ctx.json) {
-            json({
-                ref: probe.ref,
-                provider: candidate.provider,
-                model: candidate.id,
-                role,
-                ...(probe.dimensions ? { dimensions: probe.dimensions } : {}),
-                ms: probe.ms,
-                tried: tried.map(({ ref, check }) => ({ ref, ...check })),
-            });
-            return;
-        }
-        for (const t of tried.slice(0, -1)) {
-            note(`${dim(t.ref)} ${verdict(t)} ${dim(t.check.detail ?? '')}`);
-        }
-        note(`${green('works')} ${bold(probe.ref)} ${dim(ms(probe.ms))}`);
-        // stdout, alone and unstyled, so `$(zen models pick --embedding)` is
-        // the ref and nothing else.
-        write(probe.ref);
-        return;
-    }
-    bar?.done();
-    if (ctx.json) {
-        json({ ref: null, role, tried: tried.map(({ ref, check }) => ({ ref, ...check })) });
-    }
-    else {
-        writeAll(table(tried.map((t) => [
-            dim(t.ref),
-            verdict(t),
-            dim(t.check.fix ?? t.check.detail ?? ''),
-        ])));
+        // The suggestion follows what was actually asked, not what was flagged.
+        const role = failed.every((p) => p.kind === 'embedding') ? '--embeddings' : '--chat';
+        throw credentialError(`${failed.length} of ${probes.length} did not answer`, `see what else there is: zen models ls ${role}`);
     }
-    throw credentialError(`no ${role} model answered on this machine`, 'add a credential: zen key add openai');
 };
 // ---------------------------------------------------------------------------
 // browse
@@ -562,7 +519,7 @@ const pick = async (ctx, args) => {
  * one model in full, with a key to ask it a question and a key to take it.
  *
  * The interface is drawn on stderr, so a pick reaches stdout alone and
- * `$(zen models browse)` is the ref, the same contract `pick` keeps.
+ * `$(zen models browse)` is the ref.
  */
 const browse = async (ctx, args) => {
     const { values, positionals } = parse(args, { refresh: { type: 'boolean' }, theme: { type: 'string' } }, 'zen models browse [provider] [--refresh] [--theme dark|light|auto]');
@@ -571,7 +528,7 @@ const browse = async (ctx, args) => {
         throw usageError(`unknown provider "${initial}"`, `known: ${PROVIDERS.join(', ')}`);
     }
     if (ctx.json || !isInteractive()) {
-        throw usageError('browsing needs a person at a terminal', 'from a script: zen models ls --json, or zen models pick --chat');
+        throw usageError('browsing needs a person at a terminal', 'from a script: zen models ls --json');
     }
     const chosen = await browseModels({
         initial,
@@ -593,7 +550,7 @@ export async function browseModels(request = {}) {
     const where = await credentials();
     // Offline, like `providers`: the overview should not cost five listings.
     // A provider is fetched when it is opened.
-    const cats = await loadCatalogs(PROVIDERS, { offline: true });
+    const cats = await loadCatalogs(PROVIDERS, { offline: !where.gateway });
     const { browse: draw } = await import("../tui/models.js");
     return await draw({
         providers: cats.map((c) => ({
@@ -606,8 +563,11 @@ export async function browseModels(request = {}) {
         initial: request.initial,
         role: request.role,
         theme: request.theme,
+        ...(where.gateway ? { gateway: { name: GATEWAY_NAME, url: where.gateway.baseURL } } : {}),
         load: (provider, refresh) => loadCatalog(provider, { refresh: refresh || request.refresh }),
-        balance: async (provider) => provider === 'openrouter' && source(where, provider) ? routerBalance() : undefined,
+        balance: async (provider) => provider === 'openrouter' && !where.gateway && source(where, provider)
+            ? routerBalance()
+            : undefined,
         test: async (entry) => {
             const role = entry.roles.includes('chat')
                 ? 'chat'
@@ -637,12 +597,11 @@ const SUBS = {
     show: show,
     test,
     check: test,
-    pick,
     browse,
     ui: browse,
 };
 export const models = {
-    summary: 'What this machine can use: list, search, test and pick models.',
+    summary: 'What this machine can use: list, search, test and browse models.',
     usage: USAGE,
     banner: { head: 'Zenera', accent: 'Models', subtitle: 'Model Catalog', hue: 'dusk' },
     details: [
@@ -661,7 +620,6 @@ export const models = {
         '  zen models search <query>        Narrow it — --tools, --vision, --free.',
         '  zen models show <ref>            One model, in full.',
         '  zen models test <ref> …          Ask it one real question.',
-        '  zen models pick --embedding      The first ref that answers, on stdout.',
         '  zen models browse [provider]     Walk providers and models with the',
         '                                   arrow keys; t asks one, p prints its ref.',
     ],
@@ -682,7 +640,7 @@ export const models = {
             await ls(ctx, ctx.args);
             return;
         }
-        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, pick, browse')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
+        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, browse')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
     },
 };
 //# sourceMappingURL=models.js.map

package/dist/completion-install.d.ts

@@ -0,0 +1,16 @@
+declare const SHELLS: readonly ["zsh", "bash", "fish"];
+export type Shell = (typeof SHELLS)[number];
+export declare function shellOf(value: string): Shell | undefined;
+/** The primary startup file for an interactive shell. */
+export declare function rcFile(shell: Shell, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;
+/** macOS needs both login and non-login Bash startup files. */
+export declare function rcFiles(shell: Shell, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string[];
+/** Guard the loader so uninstalling zen does not break shell startup. */
+export declare function loader(shell: Shell): string;
+/** Whether `file` already loads the script; a commented-out line does not count. */
+export declare function installed(shell: Shell, file: string): boolean;
+/** Appends the loader to `file`, unless it is already there. */
+export declare function install(shell: Shell, file: string): 'added' | 'present';
+export declare function autoInstall(env?: NodeJS.ProcessEnv): void;
+export {};
+//# sourceMappingURL=completion-install.d.ts.map

package/dist/completion-install.js

@@ -0,0 +1,85 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+const SHELLS = ['zsh', 'bash', 'fish'];
+export function shellOf(value) {
+    const name = basename(value);
+    return SHELLS.find((shell) => shell === name);
+}
+/** The primary startup file for an interactive shell. */
+export function rcFile(shell, env = process.env, platform = process.platform) {
+    const home = env.HOME || homedir();
+    switch (shell) {
+        case 'zsh':
+            return join(env.ZDOTDIR || home, '.zshrc');
+        case 'bash':
+            if (platform === 'darwin') {
+                // Login Bash reads only the first existing profile in this order.
+                return (['.bash_profile', '.bash_login', '.profile']
+                    .map((name) => join(home, name))
+                    .find((file) => existsSync(file)) ?? join(home, '.bash_profile'));
+            }
+            return join(home, '.bashrc');
+        case 'fish':
+            return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'fish', 'config.fish');
+    }
+}
+/** macOS needs both login and non-login Bash startup files. */
+export function rcFiles(shell, env = process.env, platform = process.platform) {
+    const primary = rcFile(shell, env, platform);
+    return shell === 'bash' && platform === 'darwin'
+        ? [primary, join(env.HOME || homedir(), '.bashrc')]
+        : [primary];
+}
+/** Guard the loader so uninstalling zen does not break shell startup. */
+export function loader(shell) {
+    return shell === 'fish'
+        ? 'if type -q zen; zen completion fish | source; end'
+        : `if command -v zen >/dev/null 2>&1; then eval "$(zen completion ${shell})"; fi`;
+}
+/** Whether `file` already loads the script; a commented-out line does not count. */
+export function installed(shell, file) {
+    if (!existsSync(file)) {
+        return false;
+    }
+    const loads = new RegExp(`\\b(zen|zn|zenera)\\s+completion\\s+${shell}\\b`);
+    return readFileSync(file, 'utf8')
+        .split(/\r?\n/)
+        .some((line) => !line.trimStart().startsWith('#') && loads.test(line));
+}
+/** Appends the loader to `file`, unless it is already there. */
+export function install(shell, file) {
+    if (installed(shell, file)) {
+        return 'present';
+    }
+    const have = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    mkdirSync(dirname(file), { recursive: true });
+    const gap = have === '' || have.endsWith('\n\n') ? '' : have.endsWith('\n') ? '\n' : '\n\n';
+    appendFileSync(file, `${gap}# zen tab completion\n${loader(shell)}\n`);
+    return 'added';
+}
+export function autoInstall(env = process.env) {
+    // Local dependencies, npx and workspace installs must not edit shell startup.
+    if (env.npm_config_global !== 'true') {
+        return;
+    }
+    if (process.getuid?.() === 0 || env.SUDO_UID || env.SUDO_USER) {
+        console.error('zen: skipping automatic completion setup under root/sudo. Run zen completion --install as your normal user.');
+        return;
+    }
+    if (process.platform === 'win32' || (env.CI && env.CI !== 'false')) {
+        console.error('zen: skipping automatic completion setup on Windows or in CI. Run zen completion --install in a supported shell.');
+        return;
+    }
+    const shell = shellOf(env.SHELL ?? '');
+    if (!shell) {
+        console.error('zen: cannot detect a supported shell. Run zen completion <zsh|bash|fish> --install.');
+        return;
+    }
+    for (const file of rcFiles(shell, env)) {
+        const result = install(shell, file);
+        console.error(`zen: completion ${result === 'added' ? 'added to' : 'already set up in'} ${file}.`);
+    }
+    console.error('zen: open a new terminal to use tab completion.');
+}
+//# sourceMappingURL=completion-install.js.map

package/dist/completion.d.ts

@@ -0,0 +1,9 @@
+import { type Candidate } from './candidates.ts';
+/**
+ * `words` is everything typed after the program's name, the word being
+ * completed last — an empty string when the cursor follows a space.
+ */
+export declare function complete(words: readonly string[], cwd: string): Promise<Candidate[]>;
+/** The wire format. Whitespace in a description would break a line in two. */
+export declare function render(found: readonly Candidate[]): string;
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.js

@@ -0,0 +1,93 @@
+import { resolve } from 'node:path';
+import { matching, projectNames } from "./candidates.js";
+import { ALIASES, COMMANDS, EXTERNAL } from "./commands/index.js";
+import { completeMeta } from "./commands/meta.js";
+// ---------------------------------------------------------------------------
+// Shell completion
+//
+// The shell's own glue (`zen completion zsh|bash|fish`) is deliberately dumb:
+// it hands `zen __complete` the words typed so far, the one being completed
+// last, and shows whatever comes back. Everything that needs to know what a
+// project is, or which prompts it holds, is answered here, once, for all three
+// shells.
+//
+// One candidate per line, `value<TAB>description`. Nothing at all means "no
+// opinion", and the shell falls back to completing file names — which is the
+// right answer for `-C <dir>`, for `--events <file>`, and for the files that
+// follow a stored prompt.
+// ---------------------------------------------------------------------------
+/** Flags the frame owns, offered where a command name would be. */
+const GLOBAL_FLAGS = [
+    { value: '--help', description: 'Print help.' },
+    { value: '--version', description: 'Print the version.' },
+    { value: '--json', description: 'Machine-readable output.' },
+    { value: '--directory', description: 'Act as if run in <dir>.' },
+];
+/** Commands whose first bare word is a project, not a subcommand. */
+const TAKES_PROJECT = new Set(['run', 'open', 'check', 'export']);
+/** `zen key <ls|add|rm>` → `ls`, `add`, `rm`; a usage line is the only list there is. */
+function subcommands(usage) {
+    const group = /[<[]([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)[>\]]/.exec(usage);
+    return group ? group[1].split('|') : [];
+}
+/**
+ * `words` is everything typed after the program's name, the word being
+ * completed last — an empty string when the cursor follows a space.
+ */
+export async function complete(words, cwd) {
+    const cur = words.at(-1) ?? '';
+    const before = [];
+    let at = cwd;
+    for (let i = 0; i < words.length - 1; i++) {
+        const w = words[i];
+        if (w === '-C' || w === '--directory') {
+            // The directory itself is being typed: that is the shell's to complete.
+            if (i + 1 === words.length - 1) {
+                return [];
+            }
+            at = resolve(cwd, words[++i]);
+        }
+        else if (w !== '--json' && w !== '--help' && w !== '-h') {
+            before.push(w);
+        }
+    }
+    if (before.length === 0) {
+        if (cur.startsWith('-')) {
+            return matching(GLOBAL_FLAGS, cur);
+        }
+        return matching([
+            ...Object.entries(COMMANDS).map(([value, c]) => ({
+                value,
+                description: c.summary,
+            })),
+            ...Object.entries(EXTERNAL).map(([value, e]) => ({
+                value,
+                description: e.summary,
+            })),
+            { value: 'help', description: 'Help for a command.' },
+        ], cur);
+    }
+    const name = ALIASES[before[0]] ?? before[0];
+    const args = before.slice(1);
+    if (name === 'help') {
+        return args.length === 0 ? await complete([cur], at) : [];
+    }
+    if (name === 'meta') {
+        return await completeMeta(args, cur, at);
+    }
+    if (cur.startsWith('-') || args.some((a) => !a.startsWith('-'))) {
+        return [];
+    }
+    if (TAKES_PROJECT.has(name)) {
+        return matching(await projectNames(), cur);
+    }
+    const usage = COMMANDS[name]?.usage ?? EXTERNAL[name]?.usage;
+    return matching(subcommands(usage ?? '').map((value) => ({ value })), cur);
+}
+/** The wire format. Whitespace in a description would break a line in two. */
+export function render(found) {
+    return found
+        .map((c) => c.description ? `${c.value}\t${c.description.replace(/\s+/g, ' ').trim()}` : c.value)
+        .join('\n');
+}
+//# sourceMappingURL=completion.js.map

package/dist/keys.d.ts

@@ -14,9 +14,19 @@ export type Provider = (typeof PROVIDERS)[number];
  */
 export declare const SERVICES: readonly ["exa"];
 export type Service = (typeof SERVICES)[number];
+/**
+ * Somewhere every model can be reached through, with one key. Its own list for
+ * the same reason as `SERVICES`: it is neither a vendor a model comes from nor
+ * a tool, and a gateway entry only counts while the keyring is in its mode.
+ */
+export declare const GATEWAYS: readonly ["bifrost"];
+export type GatewayOwner = (typeof GATEWAYS)[number];
+/** `direct` calls each vendor with its own key; `bifrost` sends everything through the gateway. */
+export type KeyMode = 'direct' | GatewayOwner;
+export declare const MODES: readonly KeyMode[];
 /** Anything the keyring can hold a credential for. */
-export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa"];
-export type KeyOwner = Provider | Service;
+export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa", "bifrost"];
+export type KeyOwner = Provider | Service | GatewayOwner;
 /**
  * One way a credential can arrive.
  *
@@ -34,8 +44,8 @@ export interface CredentialForm {
     where: string;
 }
 interface ProviderShape {
-    /** whether this is somewhere a model lives, or something a tool calls */
-    kind: 'model' | 'service';
+    /** whether this is somewhere a model lives, something a tool calls, or a way to every model */
+    kind: 'model' | 'service' | 'gateway';
     label: string;
     /** the ways in, first being the one this provider is usually reached by */
     forms: [CredentialForm, ...CredentialForm[]];
@@ -64,6 +74,7 @@ export declare const FILE_ENVS: string[];
 export declare function envOf(entry: Pick<KeyEntry, 'provider' | 'holds' | 'env'>): string;
 export declare function isProvider(name: string): name is Provider;
 export declare function isOwner(name: string): name is KeyOwner;
+export declare function isGateway(name: string): name is GatewayOwner;
 export declare function assertOwner(name: string): KeyOwner;
 /**
  * `blocked` is the credential being fine and the *account* not: an api switched
@@ -92,6 +103,8 @@ export interface KeyEntry {
     /** vertex, file-shaped only: what the library would otherwise have to be told twice */
     project?: string;
     location?: string;
+    /** gateway only: where it listens */
+    url?: string;
     addedAt: string;
     check?: KeyCheck;
 }
@@ -122,6 +135,8 @@ export interface KeyMeta {
     project?: string;
     /** GCP region, or `global` */
     location?: string;
+    /** gateway base url */
+    url?: string;
 }
 export declare class KeyStore {
     #private;
@@ -149,6 +164,11 @@ export declare class KeyStore {
     remove(provider: KeyOwner, name: string): boolean;
     use(provider: KeyOwner, name: string): KeyEntry;
     record(entry: KeyEntry, check: KeyCheck): void;
+    /** A `BIFROST_BASE_URL` in the environment wins over the keyring, as it does for the runtime. */
+    get mode(): KeyMode;
+    get modeFrom(): 'env' | 'keyring';
+    /** Refuses a gateway mode with no gateway to send anything to. */
+    setMode(mode: KeyMode): void;
     save(): void;
     /**
      * Absolute path behind a file-shaped entry. Stored entries name a file in
@@ -175,6 +195,11 @@ export declare class KeyStore {
      *
      * Services are included by default, because a tool reads its key from the
      * environment for exactly the same reason a model adapter does.
+     *
+     * In a gateway mode the gateway's key replaces every vendor's, so those are
+     * withheld: nothing would read them, and the sandbox would be handed keys
+     * the run never needed. In `direct` mode it is the gateway that is withheld,
+     * 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. */