@zenera/cli 1.1.2 → 1.1.3

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

@@ -2,7 +2,7 @@ export { extract, invokedAs, one, parse, split, type Parsed, type Split } from '
 export { printBanner, type BannerText } from './banner.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

@@ -24,7 +24,7 @@
 export { extract, invokedAs, one, parse, split } from "./args.js";
 export { printBanner } from "./banner.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

@@ -6,18 +6,28 @@ 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][]>;
 //# sourceMappingURL=liveness.d.ts.map

package/dist/liveness.js

@@ -1,5 +1,5 @@
 import { EXA_BASE_URL, ModelRegistry } from '@zenera/neo';
-import { SHAPES, } from "./keys.js";
+import { envOf, SHAPES, } from "./keys.js";
 // ---------------------------------------------------------------------------
 // Liveness
 //
@@ -94,18 +94,61 @@ async function within(work) {
  * 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 async function probe(store, entry) {
     const shape = SHAPES[entry.provider];
     if (shape.kind === 'service') {
         return probeService(entry.provider, store.reveal(entry));
     }
-    const previous = process.env[shape.env];
-    process.env[shape.env] = store.reveal(entry);
+    const provider = entry.provider;
+    const credential = store.reveal(entry);
+    // What the entry holds, not what its provider usually holds: a Vertex
+    // express key is a secret like any other, and passing it as a value is what
+    // lets it be asked at the same time as the rest.
+    if (entry.holds !== 'file') {
+        return ask(provider, { kind: provider, apiKey: credential });
+    }
+    // A service-account file is the exception, and `probeAll` knows it:
+    // Application Default Credentials are found through the environment or not
+    // at all. So this one is exported, asked, and put back — alone.
+    const name = envOf(entry);
+    const restore = exportTemporarily({
+        [name]: credential,
+        ...(entry.project ? { GOOGLE_CLOUD_PROJECT: entry.project } : {}),
+        ...(entry.location ? { GOOGLE_CLOUD_LOCATION: entry.location } : {}),
+    });
+    try {
+        return await ask(provider, { kind: provider });
+    }
+    finally {
+        restore();
+    }
+}
+/** Sets variables, and hands back the undo. */
+function exportTemporarily(vars) {
+    const previous = new Map(Object.keys(vars).map((name) => [name, process.env[name]]));
+    Object.assign(process.env, vars);
+    return () => {
+        for (const [name, value] of previous) {
+            if (value === undefined) {
+                delete process.env[name];
+            }
+            else {
+                process.env[name] = value;
+            }
+        }
+    };
+}
+/** One authenticated round trip, and what its silence or refusal means. */
+async function ask(provider, spec) {
     try {
         const registry = new ModelRegistry();
-        registry.provider('probe', { kind: entry.provider });
-        await within(authenticate(entry.provider, registry.client('probe')));
+        registry.provider('probe', spec);
+        await within(authenticate(provider, registry.client('probe')));
         return { state: 'live', at: new Date().toISOString() };
     }
     catch (err) {
@@ -118,14 +161,6 @@ export async function probe(store, entry) {
         }
         return classify(err);
     }
-    finally {
-        if (previous === undefined) {
-            delete process.env[shape.env];
-        }
-        else {
-            process.env[shape.env] = previous;
-        }
-    }
 }
 /**
  * A service has no model catalog to list, and its cheapest endpoint is one that
@@ -200,22 +235,38 @@ async function authenticate(provider, client) {
     void result;
 }
 /**
- * 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 async function probeAll(store, entries, onProbe) {
-    const out = [];
-    for (const [index, entry] of entries.entries()) {
-        onProbe?.(entry, index, entries.length);
-        out.push([entry, await probe(store, entry)]);
+    const exclusive = (entry) => entry.holds === 'file';
+    const results = new Map();
+    let done = 0;
+    const record = (entry, check) => {
+        results.set(entry, check);
+        onProbe?.(entry, ++done, entries.length);
+    };
+    await Promise.all(entries
+        .filter((entry) => !exclusive(entry))
+        .map(async (entry) => record(entry, await probe(store, entry))));
+    for (const entry of entries.filter(exclusive)) {
+        record(entry, await probe(store, entry));
     }
-    return out;
+    // Back into the caller's order: which one answered first is an accident of
+    // the network, and a list that reshuffles itself between runs is unreadable.
+    return entries.map((entry) => [entry, results.get(entry)]);
 }
 //# sourceMappingURL=liveness.js.map

package/dist/sandbox.d.ts

@@ -26,6 +26,8 @@ export interface SandboxInputs {
     mounts?: readonly SandboxMount[];
     /** `--image` */
     image?: string;
+    /** `--no-keys`: refuse to forward credentials, whatever the config says */
+    keys?: boolean;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -1,7 +1,8 @@
 import { DEFAULT_SANDBOX_IMAGE, SANDBOX_GROUP, SandboxPool, } from '@zenera/neo';
 import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { resolveBuild } from "./image.js";
+import { credentials } from "./keys.js";
 import { ensurePodmanReady } from "./podman.js";
 import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
@@ -23,26 +24,75 @@ import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
 /** Where the persistent home lives, inside the container. */
 const HOME = '/home/agent';
+/** Where a credential *file* is mounted, inside the container. */
+const KEY_MOUNT = '/run/zenera/keys';
+/**
+ * The credentials the run is using, in the form a container takes.
+ *
+ * Two shapes, two mechanisms. A secret is forwarded by *name* — podman reads
+ * the value from its own environment, so nothing is written into an argv that
+ * `ps` will show. A service-account file has to be present as a file, so the
+ * one file is bind-mounted read-only and the variable is rewritten to where it
+ * landed; mounting the directory it came from would drag in whatever else the
+ * user keeps beside it.
+ *
+ * This is the part of the design that gives something away, and it should be
+ * said plainly: the sandbox runs code the model wrote, and a key it can read
+ * is a key it can send. `keys: false`, or `network: none`, is the answer for a
+ * project where that is not an acceptable trade.
+ */
+function forwarded() {
+    const secrets = [];
+    const env = {};
+    const mounts = [];
+    for (const cred of credentials()) {
+        if (cred.holds === 'file') {
+            const at = `${KEY_MOUNT}/${basename(cred.value)}`;
+            mounts.push({ host: cred.value, at, readOnly: true });
+            env[cred.env] = at;
+            continue;
+        }
+        secrets.push(cred.env);
+    }
+    // Not secrets, and useless without one: a service account says which
+    // project it belongs to but never which region to call.
+    for (const name of ['GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION']) {
+        const value = process.env[name];
+        if (value) {
+            env[name] = value;
+        }
+    }
+    return { secrets, env, mounts };
+}
 export function buildSandbox(opts) {
     // An explicit --image is an answer, so there is nothing left to build.
     const build = opts.image ? undefined : resolveBuild(opts.root, opts.config.sandbox);
     const base = {
         ...(opts.config.sandbox ?? {}),
         ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
+        ...(opts.keys === false ? { keys: false } : {}),
     };
     const home = join(opts.session.data, 'sandbox', 'home');
     const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
+    const keys = base.keys === false ? undefined : forwarded();
+    if (keys) {
+        mounts.push(...keys.mounts);
+    }
     // Skills and assets are mounted read-only, and a python script run from a
     // read-only directory fails on writing its own `__pycache__` — a confusing
     // error about a file nobody asked for.
-    const spec = toSpec(base, { HOME, PYTHONDONTWRITEBYTECODE: '1' });
+    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
+    const spec = toSpec(base, extra, keys?.secrets);
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
-            agents[agent.name] = toSpec(merge(base, agent.sandbox), {
-                HOME,
-                PYTHONDONTWRITEBYTECODE: '1',
-            });
+            const merged = merge(base, agent.sandbox);
+            // An agent that opts out gets neither the variables nor the mount,
+            // but the mount is on the pool and cannot be taken back per agent —
+            // so the variable is what actually decides, and without it the file
+            // sitting there is not a credential anything will look for.
+            const own = merged.keys === false ? undefined : keys;
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own?.secrets);
         }
     }
     const pool = new SandboxPool({
@@ -76,7 +126,7 @@ function merge(base, agent) {
  * is simply not forwarded — an empty string in the container is a different
  * thing from an absent one, and tools test for absence.
  */
-function toSpec(config, extra) {
+function toSpec(config, extra, secrets) {
     const env = { ...extra };
     for (const name of config.env ?? []) {
         const value = process.env[name];
@@ -94,6 +144,7 @@ function toSpec(config, extra) {
         user: config.user,
         persist: config.persist,
         env,
+        secrets,
     };
 }
 /**

package/dist/scaffold.d.ts

@@ -1,22 +1,11 @@
 /**
- * Writes `.vscode/settings.json` under `dir`, replacing what is there. The file
- * is ours: it says how the editor is to treat a directory the agents write
- * into, and a stale copy of that answer is worse than none. Returns the
- * relative path.
+ * Writes the editor's files under `dir`, replacing what is there. They are
+ * ours: they say how the editor is to treat a directory the agents write into,
+ * and they describe the file formats of the version of `zen` in hand, so the
+ * current answer is the only one worth having and a stale one is worse than
+ * none. Returns the relative paths written.
  */
-export declare function editorSettings(dir: string): string;
-/**
- * Writes the `.github/` tree under `dir`, replacing what is there — it
- * describes the file formats of the version of `zen` in hand, so the current
- * one is the only one worth having. Returns the relative paths written.
- */
-export declare function copilotInstructions(dir: string): string[];
-/**
- * Writes `sandbox/`, the Dockerfile the scaffolded `agents.yaml` builds. Unlike
- * the editor files this becomes the project's own — it is meant to be edited —
- * so anything already there is left alone.
- */
-export declare function sandboxTemplate(dir: string): string[];
+export declare function editorFiles(dir: string): string[];
 export interface ScaffoldOptions {
     /** the project directory */
     dir: string;
@@ -26,10 +15,21 @@ export interface ScaffoldOptions {
     /** give the default agent `exa:*` — set when a key for it is on hand */
     web?: boolean;
 }
+export interface Scaffolded {
+    /** the project's own files, in the order they were written */
+    files: string[];
+    /** `.vscode/` and `.github/` — written alongside, and nobody's to edit */
+    editor: string[];
+}
 /**
- * Writes a project. Never overwrites the project's own files: the caller
- * decides whether it may. The editor files are the exception — they are ours,
- * and are replaced.
+ * Writes a project. Never overwrites the project's own files — a second `init`
+ * over a directory fills in what is missing and leaves the rest alone — but the
+ * editor files are ours, and are replaced.
+ *
+ * The two are returned apart because they are read differently: the project's
+ * files are the thing that was just made, and worth listing; the editor's are
+ * plumbing for a tool that may not even be installed, and listing them buries
+ * the first set under twice as many lines about the second.
  */
-export declare function scaffold(opts: ScaffoldOptions): string[];
+export declare function scaffold(opts: ScaffoldOptions): Scaffolded;
 //# sourceMappingURL=scaffold.d.ts.map