@zenera/cli 1.1.36 → 1.1.39

package/dist/keys.d.ts

@@ -1,269 +0,0 @@
-/** The vendors a *model* can come from — the library's provider kinds, verbatim. */
-export declare const PROVIDERS: readonly ["openai", "anthropic", "google", "vertex", "openrouter"];
-export type Provider = (typeof PROVIDERS)[number];
-/**
- * Credentials that are not a way to reach a model.
- *
- * A tool can need a key as much as a model can, and the reasons a keyring
- * exists — one place, 0600, materialised into the environment before a run —
- * do not care which. What does care is everything that reasons about *models*:
- * a machine holding nothing but an Exa key cannot run an agent, and saying it
- * can would move the failure from `zen run`'s first line to its first turn.
- * Hence two lists rather than one longer one, and `kind` on the shape so the
- * few places that must tell them apart are made to say which they mean.
- */
-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", "bifrost"];
-export type KeyOwner = Provider | Service | GatewayOwner;
-/**
- * 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';
-    /** 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, 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[]];
-}
-/**
- * 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[];
-/** Variables that name a credential *file* rather than carrying the secret. */
-export declare const FILE_ENVS: 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 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
- * 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;
-    /** unique within a provider; `default` unless the user says otherwise */
-    name: string;
-    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;
-    /** gateway only: where it listens */
-    url?: string;
-    addedAt: string;
-    check?: KeyCheck;
-}
-export declare const keyId: (e: Pick<KeyEntry, "provider" | "name">) => string;
-/**
- * `provider` or `provider/name`. Returned separately rather than as a string so
- * callers cannot accidentally re-split it, and so a name that is not a legal
- * path segment is rejected here, once, before it can become a filename.
- */
-export declare function parseRef(ref: string): {
-    provider: KeyOwner;
-    name?: string;
-};
-/** Which of a provider's forms a raw value is, decided by the value itself. */
-export declare function formOf(provider: KeyOwner, raw: string): CredentialForm;
-/**
- * Throws on a name that is neither an endpoint nor shaped like a region — `usa`,
- * or `us-central` with its digit missing — because those are 404s at the first
- * call, a long way from the command that caused them. Returns false for a
- * well-formed name that is merely unrecognised, which the caller reports and
- * stores anyway: Google adds regions, and a list compiled here would be wrong
- * before it was old.
- */
-export declare function checkRegion(region: string): boolean;
-/** 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;
-    /** gateway base url */
-    url?: string;
-}
-export declare class KeyStore {
-    #private;
-    private constructor();
-    static open(): Promise<KeyStore>;
-    get entries(): readonly KeyEntry[];
-    /** Every entry for a provider, the active one first. */
-    for(provider: KeyOwner): KeyEntry[];
-    find(provider: KeyOwner, name: string): KeyEntry | undefined;
-    /** The entry a run would use, or undefined when the provider has none. */
-    active(provider: KeyOwner): KeyEntry | undefined;
-    isActive(entry: KeyEntry): boolean;
-    /**
-     * Adds or replaces. A file-shaped credential is *copied* into the key
-     * 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, meta?: KeyMeta): KeyEntry;
-    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
-     * 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;
-    /**
-     * Which GCP project a Vertex entry addresses, and how that was decided —
-     * the same order the library resolves it in, so what is shown is what will
-     * be called. A service-account file states its own project, and nothing was
-     * ever stored for it, so an entry with no `project` is not an entry with no
-     * project: it is one whose project is only knowable by reading the file.
-     */
-    projectOf(entry: KeyEntry): {
-        id: string;
-        from: 'env' | 'stored' | 'file';
-    } | undefined;
-    /**
-     * What the library would see. Real environment variables win, so CI,
-     * `docker run -e` and a one-off `OPENAI_API_KEY=… zen run` all behave
-     * exactly as they did before the store existed.
-     *
-     * 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>;
-    /**
-     * 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>;
-}
-/**
- * Enough of a secret to recognise it, never enough to use it. Short values are
- * hidden outright rather than half-shown — a twelve-character secret with eight
- * characters visible is not masked, it is inconvenienced.
- */
-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.
- *
- * Only model providers count. A keyring holding nothing but an Exa key can
- * search the web and cannot think, and reporting that as usable would trade
- * one clear error here for an obscure one on the first turn.
- */
-export declare function assertUsable(store: KeyStore): void;
-export declare function assertNotEmpty(store: KeyStore): void;
-export {};
-//# sourceMappingURL=keys.d.ts.map