@zenera/cli 1.1.0 → 1.1.3

package/dist/commands/sandbox.js

@@ -1,9 +1,15 @@
 import { readProjectConfig } from '@zenera/neo';
 import { parse } from "../args.js";
-import { ensurePodmanReady, ownedContainers, podmanStatus, removeContainers } from "../podman.js";
+import { resolveBuild } from "../image.js";
+import { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "../podman.js";
+import { dirSize, isProjectDir, Registry, sessionIds } from "../projects.js";
 import { project as findProject } from "../resolve.js";
-import { bold, dim, green, json, note, red, usageError, write, yellow } from "../term.js";
-const USAGE = 'zen sandbox [status|up|pull|clean] [options]';
+import { ago, bold, bytes, dim, green, json, note, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen sandbox [status|up|pull|clean|disk] [options]';
+/** Enough to see the pattern; the rest are a number. */
+const LISTED = 6;
+/** Under the labels, which is where the eye already is. */
+const INDENT = ' '.repeat(11);
 // ---------------------------------------------------------------------------
 // The container engine, on its own
 //
@@ -18,9 +24,10 @@ export const sandbox = {
     usage: USAGE,
     details: [
         '  status                 What is installed, running and pulled. Changes nothing.',
-        '  up                     Install if asked, start the machine, pull the image.',
-        '  pull                   Just the image.',
+        '  up                     Install if asked, start the machine, pull or build the image.',
+        '  pull                   Just the image: pulled, or built from the project\u2019s Dockerfile.',
         '  clean                  Remove every container this CLI created.',
+        '  disk                   What the engine and every known project occupy.',
         '',
         '  --project <name|dir>   Which project the image comes from.',
         '  --image <ref>          Use this image instead of the project\u2019s.',
@@ -34,22 +41,29 @@ export const sandbox = {
             image: { type: 'string' },
         }, USAGE);
         const what = positionals[0] ?? 'status';
-        if (!['status', 'up', 'pull', 'clean'].includes(what)) {
+        if (!['status', 'up', 'pull', 'clean', 'disk'].includes(what)) {
             throw usageError(`unknown subcommand: ${what}`, USAGE);
         }
         if (positionals.length > 1) {
             throw usageError('one subcommand at a time', USAGE);
         }
-        const image = values.image ?? (await projectImage(ctx.cwd, values));
+        // `clean` and `disk` are machine-wide questions, so asking which
+        // project they mean would be asking something they do not use.
+        const scoped = what === 'status' || what === 'up' || what === 'pull';
+        const found = values.image || !scoped ? undefined : await projectSandbox(ctx.cwd, values);
+        const image = values.image ?? found?.image;
+        const build = found?.build;
         switch (what) {
             case 'status':
-                return status(image, ctx.json);
+                return status(image, build, ctx.json);
             case 'up':
-                return up(image, ctx.json, ctx.json);
+                return up(image, build, ctx.json, ctx.json);
             case 'pull':
-                return up(image, true, ctx.json);
+                return up(image, build, true, ctx.json, true);
             case 'clean':
                 return clean(ctx.json);
+            case 'disk':
+                return disk(ctx.json);
         }
     },
 };
@@ -59,20 +73,22 @@ export const sandbox = {
  * not a failure — it just means there is no image to report on. Notably this
  * does *not* go through `target`: reading a setting must not create a session.
  */
-async function projectImage(cwd, values) {
+async function projectSandbox(cwd, values) {
     try {
         const found = await findProject({ cwd, project: values.project, yes: true });
-        return readProjectConfig(found.dir).config.sandbox?.image;
+        const { root, config } = readProjectConfig(found.dir);
+        const build = resolveBuild(root, config.sandbox);
+        return { image: build?.tag ?? config.sandbox?.image, build };
     }
     catch {
         return undefined;
     }
 }
-async function status(image, asJson) {
+async function status(image, build, asJson) {
     const found = await podmanStatus({ image });
     const containers = found.ready ? await ownedContainers(found.engine) : [];
     if (asJson) {
-        json({ ...found, containers });
+        json({ ...found, dockerfile: build?.dockerfile ?? null, containers });
         return;
     }
     const mark = (ok) => (ok ? green('ok') : red('no'));
@@ -85,28 +101,216 @@ async function status(image, asJson) {
     if (found.image) {
         write(`${bold('image')}      ${found.image} ${mark(Boolean(found.imagePresent))}`);
     }
-    const listed = containers.map((c) => c.state === 'running' ? `${c.name} ${green('running')}` : `${c.name} ${dim(c.state)}`);
-    write(`${bold('containers')} ${listed.length ? listed.join(', ') : dim('none')}`);
+    if (build) {
+        write(`${bold('dockerfile')} ${dim(build.dockerfile)}`);
+    }
+    writeAll(containerLines(containers));
     if (!found.installed || !found.ready) {
         note('');
         note(dim('run `zen sandbox up` to fix what can be fixed.'));
     }
 }
-async function up(image, yes, asJson) {
-    await ensurePodmanReady({ image, yes });
+/**
+ * One per line rather than one long line, because there is normally more than
+ * one and the interesting part — how old, and whether anything is still up —
+ * is at the end of a name too long to scan.
+ *
+ * The trailing note is there because the count surprises people: a container
+ * is per *session*, not per project, and `persist: true` is what leaves the
+ * stopped ones behind.
+ */
+function containerLines(containers) {
+    if (containers.length === 0) {
+        return [`${bold('containers')} ${dim('none')}`];
+    }
+    const running = containers.filter((c) => c.state === 'running').length;
+    const head = `${bold('containers')} ${containers.length} ${dim(running ? `· ${running} running` : '· none running')}`;
+    const rows = containers
+        .slice(0, LISTED)
+        .map((c) => [
+        INDENT.slice(2),
+        c.name,
+        c.state === 'running' ? green('running') : dim(c.state),
+        dim(ago(c.createdAt)),
+    ]);
+    const rest = containers.length - LISTED;
+    return [
+        head,
+        ...table(rows),
+        ...(rest > 0 ? [`${INDENT}${dim(`+${rest} more`)}`] : []),
+        `${INDENT}${dim('one per session, kept by `persist: true` — see: zen sandbox disk')}`,
+    ];
+}
+async function up(image, build, yes, asJson, rebuild = false) {
+    await ensurePodmanReady({ image, build, yes, rebuild });
     if (asJson) {
-        json({ ready: true, image });
+        json({ ready: true, image, dockerfile: build?.dockerfile ?? null });
         return;
     }
     write(`${green('ready')}${image ? ` ${dim(image)}` : ''}`);
 }
 async function clean(asJson) {
-    const names = (await ownedContainers()).map((c) => c.name);
+    const containers = await ownedContainers(undefined, undefined, { sizes: true });
+    const names = containers.map((c) => c.name);
+    const freed = containers.reduce((n, c) => n + (c.size ?? 0), 0);
     await removeContainers(names);
     if (asJson) {
-        json({ removed: names });
+        json({ removed: names, freed });
+        return;
+    }
+    if (names.length === 0) {
+        write(dim('nothing to remove'));
+        return;
+    }
+    write(`removed ${names.length} ${dim(`· ${bytes(freed)} freed`)}`);
+    write(dim('images are left alone — see: zen sandbox disk'));
+}
+async function disk(asJson) {
+    const found = await podmanStatus();
+    const [usage, containers] = found.ready
+        ? await Promise.all([
+            engineDisk(found.engine),
+            ownedContainers(found.engine, undefined, { sizes: true }),
+        ])
+        : [undefined, []];
+    const { projects, loose } = await projectDisk(containers);
+    if (asJson) {
+        json({ engine: found.engine, ready: found.ready, ...usage, projects, unclaimed: loose });
         return;
     }
-    write(names.length ? `removed ${names.length}: ${names.join(', ')}` : dim('nothing to remove'));
+    if (usage) {
+        write(`${bold('engine')} ${found.engine} ${dim(found.version ?? '')}`);
+        writeAll(engineRows(usage));
+        write('');
+    }
+    else {
+        write(dim(`${found.engine} did not answer — projects only`));
+        write('');
+    }
+    writeAll(projectRows(projects, loose));
+    if (usage && usage.images.reclaimable > 0) {
+        write('');
+        write(dim(`zen sandbox clean       every container above`));
+        write(dim(`podman image prune -a   ${bytes(usage.images.reclaimable)} of unused images`));
+    }
+}
+function engineRows(usage) {
+    // Dimming an empty cell is not empty: it is two escape codes of nothing,
+    // which `table` cannot trim and which leave trailing whitespace behind.
+    const hint = (s) => (s ? dim(s) : '');
+    const rows = [
+        [
+            bold('images'),
+            String(usage.images.count),
+            bytes(usage.images.size),
+            hint(usage.images.reclaimable > 0 ? `${bytes(usage.images.reclaimable)} unused` : ''),
+        ],
+        [
+            bold('containers'),
+            String(usage.containers.count),
+            bytes(usage.containers.size),
+            hint(usage.containers.active > 0 ? `${usage.containers.active} running` : ''),
+        ],
+        [bold('volumes'), String(usage.volumes.count), bytes(usage.volumes.size), ''],
+    ];
+    if (usage.store) {
+        rows.push([
+            bold('store'),
+            '',
+            bytes(usage.store.used),
+            hint(`of ${bytes(usage.store.capacity)}`),
+        ]);
+    }
+    if (usage.image) {
+        // The one number that is actually gone from this host's disk. It is
+        // larger than the store's own `used` because freeing blocks inside the
+        // machine does not hand them back until something trims them.
+        rows.push([
+            bold('on this host'),
+            '',
+            bytes(usage.image.allocated),
+            hint(`${usage.image.name} disk image, which never shrinks on its own`),
+        ]);
+    }
+    return table(rows);
+}
+function projectRows(projects, loose) {
+    if (projects.length === 0 && loose.length === 0) {
+        return [dim('no projects yet')];
+    }
+    const rows = [
+        [
+            bold('PROJECT'),
+            bold('SESSIONS'),
+            bold('ON DISK'),
+            bold('CONTAINERS'),
+            bold('IN PODMAN'),
+            '',
+        ],
+    ];
+    for (const p of projects) {
+        const style = p.present ? (s) => s : dim;
+        rows.push([
+            style(p.name),
+            style(String(p.sessions)),
+            style(bytes(p.files)),
+            style(p.containers ? String(p.containers) : dim('—')),
+            style(p.layers ? bytes(p.layers) : dim('—')),
+            p.present ? '' : dim('(missing)'),
+        ]);
+    }
+    if (loose.length > 0) {
+        // Containers whose session directory is gone, and faker's, which are
+        // labelled the same way and belong to no project at all.
+        const size = loose.reduce((n, c) => n + (c.size ?? 0), 0);
+        rows.push([
+            dim('(unclaimed)'),
+            dim('—'),
+            dim('—'),
+            dim(String(loose.length)),
+            dim(bytes(size)),
+            dim('no session owns these'),
+        ]);
+    }
+    const total = (pick) => projects.reduce((n, p) => n + pick(p), 0);
+    rows.push([
+        bold('total'),
+        bold(String(total((p) => p.sessions))),
+        bold(bytes(total((p) => p.files))),
+        bold(String(total((p) => p.containers) + loose.length)),
+        bold(bytes(total((p) => p.layers) + loose.reduce((n, c) => n + (c.size ?? 0), 0))),
+        '',
+    ]);
+    return table(rows);
+}
+/**
+ * Containers carry the session id that made them, and a session id is a
+ * directory name under a project — so the label is enough to attribute one,
+ * with no second index to keep in step with reality.
+ */
+async function projectDisk(containers) {
+    const registry = await Registry.open();
+    const claimed = new Set();
+    const projects = [];
+    for (const entry of registry.entries) {
+        const present = isProjectDir(entry.path);
+        const sessions = new Set(present ? sessionIds(entry.path) : []);
+        const mine = containers.filter((c) => c.key !== undefined && sessions.has(c.key));
+        for (const c of mine) {
+            claimed.add(c.name);
+        }
+        projects.push({
+            name: entry.name,
+            path: entry.path,
+            present,
+            sessions: sessions.size,
+            files: present ? dirSize(entry.path) : 0,
+            containers: mine.length,
+            layers: mine.reduce((n, c) => n + (c.size ?? 0), 0),
+        });
+    }
+    // By the column that is shown, so the order is one a reader can check.
+    projects.sort((a, b) => b.files - a.files);
+    return { projects, loose: containers.filter((c) => !claimed.has(c.name)) };
 }
 //# sourceMappingURL=sandbox.js.map

package/dist/engine.d.ts

@@ -1,5 +1,5 @@
 import { AgentRunner, type AgentEvent, type AgentProject, type AgentState, type Input, type RunResult } from '@zenera/neo';
-import type { Project } from './projects.ts';
+import { type Project } from './projects.ts';
 import { type SandboxSetup } from './sandbox.ts';
 import { type Held, type RunPaths, type SessionPaths } from './session.ts';
 export interface EngineOptions {
@@ -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

@@ -1,10 +1,11 @@
+import { AgentRunner, FileMemoryStore, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { AgentRunner, FileMemoryStore, FilePayloadStore, SANDBOX_MOUNT, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
 import { auditModels, describeIssue } from "./audit.js";
 import { readJson, writeJson } from "./home.js";
 import { KeyStore, assertUsable } from "./keys.js";
+import { projectMounts } from "./projects.js";
 import { buildSandbox, preflight, teardown, usesSandbox } from "./sandbox.js";
 import { acquire, createRun, readSessionMeta, writeSessionMeta, } from "./session.js";
 import { CliError, EXIT, invalidError, warn } from "./term.js";
@@ -35,13 +36,18 @@ export async function open(opts) {
     let sandbox;
     let project;
     try {
-        const { config } = readProjectConfig(opts.project.dir);
+        const { root, config } = readProjectConfig(opts.project.dir);
+        // Assets and the skill catalog are mounted for both, under one name.
+        const mounts = projectMounts(root, config);
         sandbox = buildSandbox({
             config,
+            root,
             session: opts.session,
             workspace,
             readOnly: opts.readOnly,
             image: opts.image,
+            keys: opts.keys,
+            mounts,
         });
         project = await loadProject(opts.project.dir, {
             tools: [
@@ -52,6 +58,7 @@ export async function open(opts) {
                     root: workspace,
                     readOnly: opts.readOnly,
                     mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+                    mounts,
                 }),
                 ...sandboxTools(sandbox.pool),
                 // Registered whether or not a key exists: the credential is
@@ -60,6 +67,7 @@ export async function open(opts) {
                 // turn that tried.
                 ...exaTools(),
             ],
+            skillsAt: SKILLS_MOUNT,
             payloads,
             memory,
         });

package/dist/image.d.ts

@@ -0,0 +1,16 @@
+import { type SandboxConfig } from '@zenera/neo';
+export interface ResolvedBuild {
+    /** the image reference to run, and to build under */
+    tag: string;
+    /** absolute path to the Dockerfile */
+    dockerfile: string;
+    /** absolute path to the build context */
+    context: string;
+}
+/**
+ * What the config's `build:` block means on this machine, or nothing if it has
+ * none. Both paths are resolved against the project root and refused if they
+ * escape it — a project is data someone else may have written.
+ */
+export declare function resolveBuild(root: string, config?: SandboxConfig): ResolvedBuild | undefined;
+//# sourceMappingURL=image.d.ts.map

package/dist/image.js

@@ -0,0 +1,85 @@
+import { projectDir, projectFile } from '@zenera/neo';
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+// ---------------------------------------------------------------------------
+// Building the sandbox image
+//
+// `image:` names something to pull; `build:` names a Dockerfile to build. The
+// library never learns the difference — it is handed a resolved reference and
+// runs it — because building is a host concern with a container engine
+// attached to it, and that is the line this CLI exists on the other side of.
+//
+// The tag is a function of what goes into the image, and it has to be: the
+// container's name in @zenera/neo hashes `spec.image`, so a tag that stayed put
+// while the Dockerfile changed would leave a `persist: true` container running
+// last week's filesystem, with nothing anywhere saying so. Hashing the context
+// as well as the Dockerfile means an edit to either yields a new tag, a new
+// container name, and a build — which is the only honest answer.
+// ---------------------------------------------------------------------------
+/** Not scoped: a `/` or an `@` is not a legal image tag. */
+const TAG = 'localhost/zenera-sandbox';
+/**
+ * A build context is meant to be small — a Dockerfile and whatever it copies.
+ * Hashing a directory someone pointed at their whole home folder would hang
+ * before it was wrong, so it stops and says which key to narrow.
+ */
+const MAX_CONTEXT_FILES = 2_000;
+/**
+ * What the config's `build:` block means on this machine, or nothing if it has
+ * none. Both paths are resolved against the project root and refused if they
+ * escape it — a project is data someone else may have written.
+ */
+export function resolveBuild(root, config) {
+    if (!config?.build) {
+        return undefined;
+    }
+    const dockerfile = projectFile(root, config.build.dockerfile, 'sandbox.build.dockerfile');
+    const context = config.build.context
+        ? projectDir(root, config.build.context, 'sandbox.build.context')
+        : dirname(dockerfile);
+    return { tag: `${TAG}:${digest(dockerfile, context)}`, dockerfile, context };
+}
+/**
+ * The content address of a build: the Dockerfile, then every file the build can
+ * see, by path and by content.
+ *
+ * `.dockerignore` is not read. The engine honours it and we do not, so an
+ * ignored file that changes yields a new tag and a build that produces the same
+ * image — wasteful, never wrong, and the alternative is reimplementing a match
+ * syntax whose disagreements would be silent.
+ */
+function digest(dockerfile, context) {
+    const hash = createHash('sha256');
+    hash.update(readFileSync(dockerfile));
+    for (const rel of walk(context)) {
+        // The separator is hashed as posix so the same tree tags the same on
+        // any host.
+        hash.update(`\0${rel.split(sep).join('/')}\0`);
+        hash.update(readFileSync(join(context, rel)));
+    }
+    return hash.digest('hex').slice(0, 12);
+}
+/** Every file under `dir`, relative and sorted, so the digest is stable. */
+function walk(dir) {
+    const found = [];
+    const pending = [dir];
+    while (pending.length > 0) {
+        const at = pending.pop();
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(path);
+            }
+            else if (entry.isFile()) {
+                found.push(relative(dir, path));
+            }
+        }
+        if (found.length > MAX_CONTEXT_FILES) {
+            throw new Error(`sandbox.build.context: ${dir} holds more than ${MAX_CONTEXT_FILES} files — ` +
+                'point `context:` at the directory the build actually copies from');
+        }
+    }
+    return found.sort();
+}
+//# sourceMappingURL=image.js.map

package/dist/keys.d.ts

@@ -17,24 +17,49 @@ 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;
@@ -52,6 +77,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 +95,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 +118,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 +155,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.