@zenera/cli 1.1.2 → 1.1.4

package/dist/liveness.js

@@ -1,5 +1,5 @@
-import { EXA_BASE_URL, ModelRegistry } from '@zenera/neo';
-import { SHAPES, } from "./keys.js";
+import { EXA_BASE_URL, ModelRegistry, text, } from '@zenera/neo';
+import { envOf, SHAPES, } from "./keys.js";
 // ---------------------------------------------------------------------------
 // Liveness
 //
@@ -7,6 +7,11 @@ import { SHAPES, } from "./keys.js";
 // the credential and said no — versus *unknown* — we could not ask. Collapsing
 // them into one red mark is the classic way to send someone hunting for the
 // wrong bug: rotating a perfectly good key because the office wifi was down.
+//
+// *blocked* is the third: the credential authenticated and the account then
+// refused. A disabled api, an empty balance, a model this key was never granted
+// — all arrive as a 403 alongside genuine rejections, and all of them are made
+// worse by rotating the key.
 // ---------------------------------------------------------------------------
 /** Words a provider uses when the credential itself is the problem. */
 const REJECTED = [
@@ -33,7 +38,38 @@ const UNREACHED = [
     'timeout',
     'socket hang up',
 ];
-function classify(err) {
+/** Words for an api the account has switched off, or never switched on. */
+const DISABLED = [
+    'service_disabled',
+    'accessnotconfigured',
+    'has not been used in project',
+    'is disabled',
+    'api is not enabled',
+];
+/** Words for an account that authenticated and then declined to serve. */
+const UNFUNDED = [
+    'insufficient_quota',
+    'billing',
+    'credit balance is too low',
+    'exceeded your current quota',
+    'quota exceeded',
+    'resource_exhausted',
+    'payment required',
+];
+/**
+ * Google names both the api and the project in its refusal, and buries them in
+ * a console url. Digging them back out turns a paragraph into the one command
+ * that fixes it.
+ */
+function enablement(message) {
+    const service = /apis\/api\/([a-z0-9.-]+\.googleapis\.com)/i.exec(message)?.[1];
+    if (!service) {
+        return undefined;
+    }
+    const project = /[?&]project=([a-z0-9-]+)/i.exec(message)?.[1];
+    return `gcloud services enable ${service}${project ? ` --project ${project}` : ''}`;
+}
+export function classify(err) {
     const at = new Date().toISOString();
     // OpenAI, Anthropic and the GenAI SDK all say `status`; OpenRouter's says
     // `statusCode`. Reading only the first would classify a revoked key as
@@ -42,6 +78,26 @@ function classify(err) {
     const status = e?.status ?? e?.statusCode;
     const message = err instanceof Error ? err.message : String(err);
     const haystack = `${status ?? ''} ${message}`.toLowerCase();
+    // Ahead of the 401/403 arm, because both of these arrive as a 403 and both
+    // are about the account rather than the key.
+    if (DISABLED.some((needle) => haystack.includes(needle))) {
+        return {
+            state: 'blocked',
+            at,
+            detail: firstLine(message),
+            fix: enablement(message) ?? 'enable the api for this project in the vendor console',
+        };
+    }
+    // A 429 is this minute's rate limit, not an empty account, and the two
+    // share vocabulary — so a status that says "slow down" wins.
+    if (status !== 429 && UNFUNDED.some((needle) => haystack.includes(needle))) {
+        return {
+            state: 'blocked',
+            at,
+            detail: firstLine(message),
+            fix: 'add credit or raise the quota in the vendor console',
+        };
+    }
     if (status === 401 || status === 403) {
         return { state: 'dead', at, detail: `${status} ${firstLine(message)}` };
     }
@@ -58,7 +114,29 @@ function classify(err) {
     }
     return { state: 'unknown', at, detail: firstLine(message) };
 }
-const firstLine = (s) => s.split('\n')[0].slice(0, 160);
+/**
+ * The one sentence worth showing.
+ *
+ * Google's SDK throws with the whole JSON error body as the message, and a
+ * table cell holding `{"error":{"code":403,"message":"…` is a cell nobody
+ * reads. The sentence inside it is the part a person or an agent acts on, so
+ * that is what comes out when there is one.
+ */
+const firstLine = (s) => {
+    const start = s.indexOf('{');
+    if (start !== -1) {
+        try {
+            const body = JSON.parse(s.slice(start));
+            if (typeof body.error?.message === 'string') {
+                return body.error.message.split('\n')[0].slice(0, 200);
+            }
+        }
+        catch {
+            // Not JSON, or truncated JSON. The raw line is still better than nothing.
+        }
+    }
+    return s.split('\n')[0].slice(0, 200);
+};
 // ---------------------------------------------------------------------------
 // Deadline
 //
@@ -69,15 +147,20 @@ const firstLine = (s) => s.split('\n')[0].slice(0, 160);
 // been answered by now, the honest answer is *unknown*.
 // ---------------------------------------------------------------------------
 const DEADLINE_MS = 15_000;
+/**
+ * A model is asked to think, not merely to authenticate, so it is given longer
+ * — a reasoning model can spend half a minute on one word and still be working.
+ */
+const MODEL_DEADLINE_MS = 90_000;
 class Deadline extends Error {
 }
-async function within(work) {
+async function within(work, ms = DEADLINE_MS) {
     let timer;
     try {
         return await Promise.race([
             work,
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Deadline()), DEADLINE_MS);
+                timer = setTimeout(() => reject(new Deadline()), ms);
                 // The abandoned request must not keep the process alive.
                 timer.unref?.();
             }),
@@ -94,18 +177,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 +244,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 +318,144 @@ 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));
+    }
+    // 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)]);
+}
+// ---------------------------------------------------------------------------
+// Models
+//
+// A credential that authenticates says nothing about the model id it is spent
+// on: `gemini-3.5-flash` with an OpenAI key, a deprecated snapshot, a model the
+// account was never granted — all of them pass every check this file otherwise
+// performs and then fail on the first turn of a real run. The only thing that
+// answers the question is asking the model itself, so this asks it: one word
+// in, one word out, per distinct model the project would use.
+// ---------------------------------------------------------------------------
+/** Words a vendor uses when the credential was fine and the model id was not. */
+const UNSERVED = [
+    'model_not_found',
+    'does not exist',
+    'not found',
+    'unknown model',
+    'invalid model',
+    'no endpoints found',
+    'is not supported',
+    'not supported',
+    'no access',
+];
+const targetId = (target) => target.kind === 'model' ? target.model.id : target.embedder.id;
+/**
+ * Refused by the provider, unreachable, or served.
+ *
+ * A model this account cannot use is `blocked`, not `dead`: the credential was
+ * accepted and the id was the thing refused, so the fix is another model rather
+ * than another key. `dead` is left to mean the credential itself was rejected.
+ */
+function classifyModel(err, target) {
+    const at = new Date().toISOString();
+    const message = err instanceof Error ? err.message : String(err);
+    const e = err;
+    const haystack = `${e?.status ?? e?.statusCode ?? ''} ${message}`.toLowerCase();
+    if (err instanceof Deadline || e?.name === 'AbortError' || e?.name === 'TimeoutError') {
+        return { state: 'unknown', at, detail: `no answer in ${MODEL_DEADLINE_MS / 1000}s` };
+    }
+    if (UNSERVED.some((needle) => haystack.includes(needle))) {
+        return { state: 'blocked', at, detail: firstLine(message), fix: instead(target) };
     }
-    return out;
+    const check = classify(err);
+    return check.state === 'blocked' && !check.fix ? { ...check, fix: instead(target) } : check;
+}
+/** The command that finds something this account can actually use. */
+function instead(target) {
+    const provider = target.ref.includes(':') ? target.ref.split(':')[0] : undefined;
+    return provider
+        ? `zen models ls ${provider}`
+        : `zen models pick --${target.kind === 'embedding' ? 'embedding' : 'chat'}`;
+}
+/**
+ * The smallest real call the model can be asked for. It costs a handful of
+ * tokens, which is the point: anything cheaper than a completion does not
+ * exercise the thing that breaks.
+ *
+ * An embedding answers with its width, which is worth carrying back: a model
+ * that serves the wrong number of dimensions is not interchangeable with the
+ * one an index was built on.
+ */
+async function askModel(target, signal) {
+    if (target.kind === 'embedding') {
+        const res = await target.embedder.embed({ input: ['ping'], signal });
+        return res.dimensions;
+    }
+    await target.model.generate({
+        system: 'Reply with the single word: ok',
+        messages: [{ role: 'user', content: [text('ping')] }],
+        tools: [],
+        signal,
+    });
+    return undefined;
+}
+export async function probeModel(target) {
+    const started = Date.now();
+    const common = { ref: target.ref, id: targetId(target), kind: target.kind };
+    try {
+        // The signal cancels the request; the deadline a little behind it is
+        // the answer for an SDK that decides to ignore the signal.
+        const work = askModel(target, AbortSignal.timeout(MODEL_DEADLINE_MS));
+        const dimensions = await within(work, MODEL_DEADLINE_MS + 5_000);
+        return {
+            ...common,
+            check: { state: 'live', at: new Date().toISOString() },
+            ms: Date.now() - started,
+            ...(dimensions === undefined ? {} : { dimensions }),
+        };
+    }
+    catch (err) {
+        return { ...common, check: classifyModel(err, target), ms: Date.now() - started };
+    }
+}
+/**
+ * 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 async function probeModels(targets, onProbe) {
+    let done = 0;
+    return await Promise.all(targets.map(async (target) => {
+        const result = await probeModel(target);
+        onProbe?.(target, ++done, targets.length);
+        return result;
+    }));
 }
 //# 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