@zenera/cli 1.1.2 → 1.1.4

package/dist/commands/open.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { delimiter, join, resolve, sep } from 'node:path';
 import { one, parse } from "../args.js";
 import { project as resolveProject } from "../resolve.js";
-import { copilotInstructions, editorSettings } from "../scaffold.js";
+import { editorFiles } from "../scaffold.js";
 import { CliError, cyan, dim, EXIT, json, note, usageError } from "../term.js";
 const USAGE = 'zen open [project] [--editor <cmd>] [--wait]';
 /**
@@ -42,7 +42,7 @@ export const open = {
         // opened on, and a project may predate either of them — or the version
         // this `zen` writes. They are ours, so they are written fresh before
         // the window is there to read them.
-        const written = [editorSettings(dir), ...copilotInstructions(dir)];
+        const written = editorFiles(dir);
         if (ctx.json) {
             json({
                 name: found.name,

package/dist/commands/run.js

@@ -19,6 +19,7 @@ export const run = {
         '  --model <ref>          Override the default model.',
         '  --image <ref>          Override the sandbox image commands run in.',
         '  --read-only            Give the agent no way to write.',
+        '  --no-keys              Keep the API keys out of the sandbox.',
         '  --quiet                Answer only; no narration.',
         '  --plain                One shot, even on a terminal.',
         '  --theme <dark|light>   Force the palette. Detected otherwise; $ZENERA_THEME.',
@@ -43,6 +44,7 @@ export const run = {
             workspace: { type: 'string' },
             model: { type: 'string' },
             image: { type: 'string' },
+            'no-keys': { type: 'boolean' },
             'read-only': { type: 'boolean' },
             yes: { type: 'boolean' },
             quiet: { type: 'boolean' },
@@ -84,6 +86,7 @@ export const run = {
             readOnly: values['read-only'],
             model: values.model,
             image: values.image,
+            keys: values['no-keys'] ? false : undefined,
             yes: values.yes || ctx.json,
         });
         try {

package/dist/engine.d.ts

@@ -10,6 +10,8 @@ export interface EngineOptions {
     model?: string;
     /** sandbox image override — `--image` */
     image?: string;
+    /** whether credentials reach the sandbox — `--no-keys` sets this false */
+    keys?: boolean;
     /** answer the sandbox's install question without asking — `--yes` */
     yes?: boolean;
 }

package/dist/engine.js

@@ -46,6 +46,7 @@ export async function open(opts) {
             workspace,
             readOnly: opts.readOnly,
             image: opts.image,
+            keys: opts.keys,
             mounts,
         });
         project = await loadProject(opts.project.dir, {

package/dist/home.d.ts

@@ -5,6 +5,8 @@ export declare const paths: {
     keys: () => string;
     keyDir: () => string;
     faker: () => string;
+    /** cached model listings, one file per provider — public data, not secrets */
+    catalog: () => string;
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export declare function ensureDir(dir: string, mode?: number): string;

package/dist/home.js

@@ -26,6 +26,8 @@ export const paths = {
     keys: () => join(home(), 'keys.json'),
     keyDir: () => join(home(), 'keys'),
     faker: () => join(home(), 'faker'),
+    /** cached model listings, one file per provider — public data, not secrets */
+    catalog: () => join(home(), 'catalog'),
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export function ensureDir(dir, mode = DIR_MODE) {

package/dist/keys.d.ts

@@ -17,33 +17,66 @@ export type Service = (typeof SERVICES)[number];
 /** Anything the keyring can hold a credential for. */
 export declare const OWNERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter", "exa"];
 export type KeyOwner = Provider | Service;
-interface ProviderShape {
-    /** whether this is somewhere a model lives, or something a tool calls */
-    kind: 'model' | 'service';
-    /** environment variable the library reads */
-    env: string;
+/**
+ * One way a credential can arrive.
+ *
+ * A provider that accepts two accepts two of these, and they agree about
+ * nothing: not the variable, not whether the value is the secret or a path to
+ * it, not where you go to get one. So the alternative is a whole form rather
+ * than a wider `holds`.
+ */
+export interface CredentialForm {
     /** what the value is: a secret string, or a path to a credentials file */
     holds: 'secret' | 'file';
-    label: string;
+    /** environment variable the library reads */
+    env: string;
     /** where to get one, printed when there is none */
     where: string;
 }
+interface ProviderShape {
+    /** whether this is somewhere a model lives, or something a tool calls */
+    kind: 'model' | 'service';
+    label: string;
+    /** the ways in, first being the one this provider is usually reached by */
+    forms: [CredentialForm, ...CredentialForm[]];
+}
 /**
- * Vertex is the odd one. The GenAI SDK resolves Application Default
- * Credentials itself, so what is stored is a service-account *file* and what is
- * exported is a path — not a key. Pretending otherwise would mean inventing a
- * credential shape Google does not have.
+ * Vertex is the odd one, and it is odd twice.
+ *
+ * Its usual credential is not a key at all: the GenAI SDK resolves Application
+ * Default Credentials itself, so what is stored is a service-account *file* and
+ * what is exported is a path. But it also accepts an express-mode api key,
+ * which is an ordinary secret under an entirely different variable. The two are
+ * alternatives — express mode addresses no project — so which form a credential
+ * is gets decided per entry rather than per provider.
  */
 export declare const SHAPES: Record<KeyOwner, ProviderShape>;
+/**
+ * The form a provider is usually reached by — for the questions that have to
+ * have one answer, like which variable to name when nothing is set yet.
+ */
+export declare function form(provider: KeyOwner): CredentialForm;
+/** Every variable a provider's credential could arrive in, usual one first. */
+export declare function envNames(provider: KeyOwner): string[];
+/** The variable this particular credential occupies. */
+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 assertOwner(name: string): KeyOwner;
-export type Liveness = 'live' | 'dead' | 'unknown';
+/**
+ * `blocked` is the credential being fine and the *account* not: an api switched
+ * off in the project, a spent balance, a model this key was never granted. It
+ * is split out of `dead` because the two want opposite actions — rotating a key
+ * that authenticated perfectly is the wrong afternoon.
+ */
+export type Liveness = 'live' | 'dead' | 'blocked' | 'unknown';
 export interface KeyCheck {
     state: Liveness;
     at: string;
     /** the provider's own words when it said no, or ours when we could not ask */
     detail?: string;
+    /** what to actually do about it, when the refusal implies something specific */
+    fix?: string;
 }
 export interface KeyEntry {
     provider: KeyOwner;
@@ -52,6 +85,11 @@ export interface KeyEntry {
     holds: 'secret' | 'file';
     /** the secret itself, or a path relative to the key directory */
     value: string;
+    /** the variable it is exported as; absent on entries written before providers had two */
+    env?: string;
+    /** vertex, file-shaped only: what the library would otherwise have to be told twice */
+    project?: string;
+    location?: string;
     addedAt: string;
     check?: KeyCheck;
 }
@@ -65,6 +103,13 @@ export declare function parseRef(ref: string): {
     provider: KeyOwner;
     name?: string;
 };
+/** What a credential cannot say about itself. */
+export interface KeyMeta {
+    /** GCP project id, for a Vertex service account */
+    project?: string;
+    /** GCP region, or `global` */
+    location?: string;
+}
 export declare class KeyStore {
     #private;
     private constructor();
@@ -81,13 +126,21 @@ export declare class KeyStore {
      * directory: the point of a store is that the credential survives the
      * original being moved, renamed or cleaned up, and a stored path that
      * silently stops resolving is worse than no store at all.
+     *
+     * Which form a value is, when the provider accepts two, is read off the
+     * value: a path that is there is a credentials file, and anything else is a
+     * secret. Asking would be a flag to get wrong, and a service-account key
+     * and an api key are not mistakable for one another.
      */
-    add(provider: KeyOwner, name: string, raw: string): KeyEntry;
+    add(provider: KeyOwner, name: string, raw: string, meta?: KeyMeta): KeyEntry;
     remove(provider: KeyOwner, name: string): boolean;
     use(provider: KeyOwner, name: string): KeyEntry;
     record(entry: KeyEntry, check: KeyCheck): void;
     save(): void;
-    /** Absolute path behind a file-shaped entry. */
+    /**
+     * Absolute path behind a file-shaped entry. Stored entries name a file in
+     * the key directory; an ambient one already knows where it is.
+     */
     fileOf(entry: KeyEntry): string;
     /** The plaintext an entry stands for — the only way out of the store. */
     reveal(entry: KeyEntry): string;
@@ -110,6 +163,44 @@ export declare class KeyStore {
  */
 export declare function mask(secret: string): string;
 export declare function describe(store: KeyStore, entry: KeyEntry): string;
+/**
+ * A credential the keyring does not hold but the libraries will nonetheless
+ * find: a variable already in the environment, or the file `gcloud auth
+ * application-default login` writes.
+ *
+ * These have to be listed, because they are the reason a provider works when
+ * `zen key ls` says there is nothing for it — and the reason one keeps working
+ * after its entry is removed.
+ */
+export interface Ambient {
+    provider: KeyOwner;
+    /** the variable it arrived in; absent when it was found where the SDK looks */
+    env?: string;
+    holds: 'secret' | 'file';
+    value: string;
+}
+/** How an ambient credential is named on the command line: it has no key name. */
+export declare function ambientId(cred: Ambient): string;
+/**
+ * Where `gcloud auth application-default login` leaves its credentials. The
+ * GenAI SDK reads this without being told to, so it counts even though nothing
+ * in the environment mentions it.
+ */
+export declare function gcloudAdc(): string | undefined;
+export declare function ambient(store: KeyStore, only?: KeyOwner[]): Ambient[];
+/**
+ * Every credential variable this process is carrying, whatever put it there.
+ *
+ * Read off the environment rather than off the store, and deliberately: by the
+ * time anyone asks, `materialize()` has already run, so the environment is the
+ * union of the keyring and whatever the shell brought — which is exactly the
+ * set of credentials the run is actually using.
+ */
+export declare function credentials(): {
+    env: string;
+    holds: 'secret' | 'file';
+    value: string;
+}[];
 /**
  * Called before a run: says plainly that there is no way to reach a model,
  * rather than letting the SDK raise it three frames deeper as a 401.

package/dist/keys.js

@@ -1,6 +1,7 @@
-import { chmodSync, copyFileSync, existsSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
 import { EXA_API_KEY_ENV } from '@zenera/neo';
+import { chmodSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
 import { assertPrivate, ensureDir, paths, readJson, writeJson } from "./home.js";
 import { CliError, EXIT, credentialError, usageError } from "./term.js";
 // ---------------------------------------------------------------------------
@@ -33,55 +34,108 @@ export const SERVICES = ['exa'];
 /** Anything the keyring can hold a credential for. */
 export const OWNERS = [...PROVIDERS, ...SERVICES];
 /**
- * Vertex is the odd one. The GenAI SDK resolves Application Default
- * Credentials itself, so what is stored is a service-account *file* and what is
- * exported is a path — not a key. Pretending otherwise would mean inventing a
- * credential shape Google does not have.
+ * Vertex is the odd one, and it is odd twice.
+ *
+ * Its usual credential is not a key at all: the GenAI SDK resolves Application
+ * Default Credentials itself, so what is stored is a service-account *file* and
+ * what is exported is a path. But it also accepts an express-mode api key,
+ * which is an ordinary secret under an entirely different variable. The two are
+ * alternatives — express mode addresses no project — so which form a credential
+ * is gets decided per entry rather than per provider.
  */
 export const SHAPES = {
     openai: {
         kind: 'model',
-        env: 'OPENAI_API_KEY',
-        holds: 'secret',
         label: 'OpenAI',
-        where: 'https://platform.openai.com/api-keys',
+        forms: [
+            {
+                holds: 'secret',
+                env: 'OPENAI_API_KEY',
+                where: 'https://platform.openai.com/api-keys',
+            },
+        ],
     },
     anthropic: {
         kind: 'model',
-        env: 'ANTHROPIC_API_KEY',
-        holds: 'secret',
         label: 'Anthropic',
-        where: 'https://console.anthropic.com/settings/keys',
+        forms: [
+            {
+                holds: 'secret',
+                env: 'ANTHROPIC_API_KEY',
+                where: 'https://console.anthropic.com/settings/keys',
+            },
+        ],
     },
     google: {
         kind: 'model',
-        env: 'GEMINI_API_KEY',
-        holds: 'secret',
         label: 'Google AI Studio',
-        where: 'https://aistudio.google.com/apikey',
+        forms: [
+            {
+                holds: 'secret',
+                env: 'GEMINI_API_KEY',
+                where: 'https://aistudio.google.com/apikey',
+            },
+        ],
     },
     vertex: {
         kind: 'model',
-        env: 'GOOGLE_APPLICATION_CREDENTIALS',
-        holds: 'file',
         label: 'Vertex AI',
-        where: 'a service-account JSON key from the GCP console',
+        forms: [
+            {
+                holds: 'file',
+                env: 'GOOGLE_APPLICATION_CREDENTIALS',
+                where: 'a service-account JSON key from the GCP console',
+            },
+            {
+                holds: 'secret',
+                env: 'VERTEX_API_KEY',
+                where: 'an express-mode key from https://console.cloud.google.com/vertex-ai',
+            },
+        ],
     },
     openrouter: {
         kind: 'model',
-        env: 'OPENROUTER_API_KEY',
-        holds: 'secret',
         label: 'OpenRouter',
-        where: 'https://openrouter.ai/settings/keys',
+        forms: [
+            {
+                holds: 'secret',
+                env: 'OPENROUTER_API_KEY',
+                where: 'https://openrouter.ai/settings/keys',
+            },
+        ],
     },
     exa: {
         kind: 'service',
-        env: EXA_API_KEY_ENV,
-        holds: 'secret',
         label: 'Exa',
-        where: 'https://dashboard.exa.ai/api-keys',
+        forms: [
+            {
+                holds: 'secret',
+                env: EXA_API_KEY_ENV,
+                where: 'https://dashboard.exa.ai/api-keys',
+            },
+        ],
     },
 };
+/**
+ * The form a provider is usually reached by — for the questions that have to
+ * have one answer, like which variable to name when nothing is set yet.
+ */
+export function form(provider) {
+    return SHAPES[provider].forms[0];
+}
+/** Every variable a provider's credential could arrive in, usual one first. */
+export function envNames(provider) {
+    return SHAPES[provider].forms.map((f) => f.env);
+}
+/** The variable this particular credential occupies. */
+export function envOf(entry) {
+    if (entry.env) {
+        return entry.env;
+    }
+    // Entries written before a provider had two forms carry no `env` of their own.
+    const forms = SHAPES[entry.provider].forms;
+    return (forms.find((f) => f.holds === entry.holds) ?? forms[0]).env;
+}
 export function isProvider(name) {
     return PROVIDERS.includes(name);
 }
@@ -114,6 +168,15 @@ export function parseRef(ref) {
     }
     return { provider, name };
 }
+/** Which of a provider's forms a raw value is, decided by the value itself. */
+function formOf(provider, raw) {
+    const { forms } = SHAPES[provider];
+    if (forms.length === 1) {
+        return forms[0];
+    }
+    const wanted = raw.length < 4096 && existsSync(resolve(raw)) ? 'file' : 'secret';
+    return forms.find((f) => f.holds === wanted) ?? forms[0];
+}
 // ---------------------------------------------------------------------------
 // Store
 // ---------------------------------------------------------------------------
@@ -160,17 +223,27 @@ export class KeyStore {
      * directory: the point of a store is that the credential survives the
      * original being moved, renamed or cleaned up, and a stored path that
      * silently stops resolving is worse than no store at all.
+     *
+     * Which form a value is, when the provider accepts two, is read off the
+     * value: a path that is there is a credentials file, and anything else is a
+     * secret. Asking would be a flag to get wrong, and a service-account key
+     * and an api key are not mistakable for one another.
      */
-    add(provider, name, raw) {
+    add(provider, name, raw, meta = {}) {
         if (!NAME.test(name)) {
             throw usageError(`"${name}" is not a usable key name`, 'letters, digits, - and _ only');
         }
-        const shape = SHAPES[provider];
+        const form = formOf(provider, raw);
         const entry = {
             provider,
             name,
-            holds: shape.holds,
-            value: shape.holds === 'file' ? this.#absorb(provider, name, raw) : raw,
+            holds: form.holds,
+            value: form.holds === 'file' ? this.#absorb(provider, name, raw) : raw,
+            env: form.env,
+            // Express mode addresses no project, so carrying one would only ever
+            // be a way to build the combination the service refuses.
+            ...(form.holds === 'file' && meta.project ? { project: meta.project } : {}),
+            ...(form.holds === 'file' && meta.location ? { location: meta.location } : {}),
             addedAt: new Date().toISOString(),
         };
         const at = this.#file.entries.findIndex((e) => e.provider === provider && e.name === name);
@@ -216,9 +289,12 @@ export class KeyStore {
         ensureDir(paths.home());
         writeJson(paths.keys(), this.#file);
     }
-    /** Absolute path behind a file-shaped entry. */
+    /**
+     * Absolute path behind a file-shaped entry. Stored entries name a file in
+     * the key directory; an ambient one already knows where it is.
+     */
     fileOf(entry) {
-        return join(paths.keyDir(), entry.value);
+        return isAbsolute(entry.value) ? entry.value : join(paths.keyDir(), entry.value);
     }
     /** The plaintext an entry stands for — the only way out of the store. */
     reveal(entry) {
@@ -239,11 +315,18 @@ export class KeyStore {
             if (!entry) {
                 continue;
             }
-            const { env: name } = SHAPES[provider];
-            if (process.env[name]) {
+            // Either variable being set means this provider is already answered
+            // for, so the stored alternative must not be exported alongside it.
+            if (envNames(provider).some((name) => process.env[name])) {
                 continue;
             }
-            env[name] = this.reveal(entry);
+            env[envOf(entry)] = this.reveal(entry);
+            if (entry.project && !process.env.GOOGLE_CLOUD_PROJECT) {
+                env.GOOGLE_CLOUD_PROJECT = entry.project;
+            }
+            if (entry.location && !process.env.GOOGLE_CLOUD_LOCATION) {
+                env.GOOGLE_CLOUD_LOCATION = entry.location;
+            }
         }
         return env;
     }
@@ -284,6 +367,64 @@ export function mask(secret) {
 export function describe(store, entry) {
     return entry.holds === 'file' ? store.fileOf(entry) : mask(entry.value);
 }
+/** How an ambient credential is named on the command line: it has no key name. */
+export function ambientId(cred) {
+    return cred.env ? `${cred.provider}/$${cred.env}` : `${cred.provider}/adc`;
+}
+/**
+ * Where `gcloud auth application-default login` leaves its credentials. The
+ * GenAI SDK reads this without being told to, so it counts even though nothing
+ * in the environment mentions it.
+ */
+export function gcloudAdc() {
+    const dir = process.env.CLOUDSDK_CONFIG ?? join(homedir(), '.config', 'gcloud');
+    const path = join(dir, 'application_default_credentials.json');
+    return existsSync(path) ? path : undefined;
+}
+export function ambient(store, only) {
+    const found = [];
+    for (const provider of only ?? OWNERS) {
+        for (const form of SHAPES[provider].forms) {
+            const value = process.env[form.env];
+            if (!value) {
+                continue;
+            }
+            // `materialize()` puts the store's own entries here. Reporting one
+            // of those as ambient would double-count it, and would claim the
+            // environment as a source that would survive removing the entry.
+            const active = store.active(provider);
+            if (active && envOf(active) === form.env && store.reveal(active) === value) {
+                continue;
+            }
+            found.push({ provider, env: form.env, holds: form.holds, value });
+        }
+    }
+    const adc = (only ?? OWNERS).includes('vertex') ? gcloudAdc() : undefined;
+    if (adc && !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+        found.push({ provider: 'vertex', holds: 'file', value: adc });
+    }
+    return found;
+}
+/**
+ * Every credential variable this process is carrying, whatever put it there.
+ *
+ * Read off the environment rather than off the store, and deliberately: by the
+ * time anyone asks, `materialize()` has already run, so the environment is the
+ * union of the keyring and whatever the shell brought — which is exactly the
+ * set of credentials the run is actually using.
+ */
+export function credentials() {
+    const found = [];
+    for (const provider of OWNERS) {
+        for (const form of SHAPES[provider].forms) {
+            const value = process.env[form.env];
+            if (value) {
+                found.push({ env: form.env, holds: form.holds, value });
+            }
+        }
+    }
+    return found;
+}
 // ---------------------------------------------------------------------------
 // Gate
 // ---------------------------------------------------------------------------
@@ -296,7 +437,7 @@ export function describe(store, entry) {
  * one clear error here for an obscure one on the first turn.
  */
 export function assertUsable(store) {
-    const reachable = PROVIDERS.filter((p) => process.env[SHAPES[p].env] || store.active(p) !== undefined);
+    const reachable = PROVIDERS.filter((p) => envNames(p).some((name) => process.env[name]) || store.active(p) !== undefined);
     if (reachable.length === 0) {
         throw credentialError('no credentials for any provider', 'add one with: zen key add openai');
     }

package/dist/lib.d.ts

@@ -1,8 +1,9 @@
 export { extract, invokedAs, one, parse, split, type Parsed, type Split } from './args.ts';
 export { printBanner, type BannerText } from './banner.ts';
+export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, type Catalog, type CatalogEntry, type CatalogOptions, type Filters, type Role, } from './catalog.ts';
 export type { Command, Context } from './command.ts';
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from './home.ts';
-export { assertNotEmpty, assertOwner, assertUsable, describe, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, type KeyCheck, type KeyEntry, type KeyOwner, type Liveness, type Provider, type Service, } from './keys.ts';
+export { assertNotEmpty, assertOwner, assertUsable, describe, envNames, envOf, form, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, type CredentialForm, type KeyCheck, type KeyEntry, type KeyOwner, type Liveness, type Provider, type Service, } from './keys.ts';
 export { probe, probeAll } from './liveness.ts';
 export { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, type DiskLine, type EngineDisk, type OwnedContainer, type PodmanOptions, type PodmanStatus, } from './podman.ts';
 export { ago, bold, CliError, count, credentialError, cyan, dim, EXIT, fail, green, invalidError, isInteractive, json, note, pad, red, table, usageError, warn, write, writeAll, yellow, type ExitCode, } from './term.ts';

package/dist/lib.js

@@ -23,8 +23,9 @@
 // ---------------------------------------------------------------------------
 export { extract, invokedAs, one, parse, split } from "./args.js";
 export { printBanner } from "./banner.js";
+export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, } from "./catalog.js";
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from "./home.js";
-export { assertNotEmpty, assertOwner, assertUsable, describe, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, } from "./keys.js";
+export { assertNotEmpty, assertOwner, assertUsable, describe, envNames, envOf, form, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, } from "./keys.js";
 export { probe, probeAll } from "./liveness.js";
 export { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "./podman.js";
 export { ago, bold, CliError, count, credentialError, cyan, dim, EXIT, fail, green, invalidError, isInteractive, json, note, pad, red, table, usageError, warn, write, writeAll, yellow, } from "./term.js";

package/dist/liveness.d.ts

@@ -1,4 +1,6 @@
+import { type Embedder, type Model } from '@zenera/neo';
 import { type KeyCheck, type KeyEntry, type KeyStore } from './keys.ts';
+export declare function classify(err: unknown): KeyCheck;
 /**
  * The cheapest authenticated call each SDK has. Nothing here reads a model or
  * spends a token: the question is only whether the credential is accepted.
@@ -6,18 +8,58 @@ import { type KeyCheck, type KeyEntry, type KeyStore } from './keys.ts';
  * The client is built through the library's own registry rather than by
  * requiring the SDKs directly, so a missing optional dependency produces the
  * library's "run: npm i openai" message instead of a raw MODULE_NOT_FOUND.
+ *
+ * A secret is handed to the registry as a value rather than exported first,
+ * which is what lets several of these run at once: two probes sharing
+ * `process.env` would each read the other's key.
  */
 export declare function probe(store: KeyStore, entry: KeyEntry): Promise<KeyCheck>;
 /**
- * Probes many entries, one at a time. In flight together would be quicker, but
- * `probe` reaches the SDKs the only way they can be reached — through
- * `process.env` — and two probes sharing that variable would each read the
- * other's key. One at a time is also what makes progress reportable: there is
- * exactly one answer being waited on, and `onProbe` can name it.
+ * Probes many entries together, because they are independent questions asked
+ * of different vendors and the answer is a round trip apiece: in sequence,
+ * five keys is five deadlines end to end, and `zen init` spends them all
+ * before it writes a file.
+ *
+ * The exception is a credential the SDK can only be given through the
+ * environment — the vertex service-account file — since two of those in flight
+ * would each read the other's path. Those go one at a time, after the rest.
+ *
+ * `onProbe` therefore reports what has *finished* rather than what is being
+ * waited on; with several in the air there is no single one to name.
  *
  * Pairs rather than a map, because the caller needs the entry itself to record
  * the result against, and a map keyed by a string would only have to be
  * un-joined again.
  */
-export declare function probeAll(store: KeyStore, entries: readonly KeyEntry[], onProbe?: (entry: KeyEntry, index: number, total: number) => void): Promise<[KeyEntry, KeyCheck][]>;
+export declare function probeAll(store: KeyStore, entries: readonly KeyEntry[], onProbe?: (entry: KeyEntry, done: number, total: number) => void): Promise<[KeyEntry, KeyCheck][]>;
+/** What the project calls a model, and the thing that call resolved to. */
+export type ModelTarget = {
+    ref: string;
+    kind: 'model';
+    model: Model;
+} | {
+    ref: string;
+    kind: 'embedding';
+    embedder: Embedder;
+};
+export interface ModelProbe {
+    /** the reference as the config writes it — an alias, or a full ref */
+    ref: string;
+    /** the id that goes on the wire */
+    id: string;
+    kind: 'model' | 'embedding';
+    check: KeyCheck;
+    /** how long the round trip took, for the one that is merely slow */
+    ms: number;
+    /** embeddings only: the width the model actually returned */
+    dimensions?: number;
+}
+export declare function probeModel(target: ModelTarget): Promise<ModelProbe>;
+/**
+ * One round trip per model, run together — they are independent questions, and
+ * a project with four models should not take four deadlines to answer. Nothing
+ * here touches `process.env`, so unlike the credential probes there is no case
+ * that has to go alone.
+ */
+export declare function probeModels(targets: readonly ModelTarget[], onProbe?: (target: ModelTarget, done: number, total: number) => void): Promise<ModelProbe[]>;
 //# sourceMappingURL=liveness.d.ts.map