@zenera/cli 1.1.24 → 1.1.26

package/README.md

@@ -241,6 +241,7 @@ so they never go stale - and edits to them do not survive.
 | `/spec-sync-project`   | Makes every file match `SPECIFICATION.md`, both directions.      |
 | `/spec-apply-feedback` | Folds your answers in `SPECIFICATION-FEEDBACK.md` into the spec. |
 | `/project-review`      | Reads the project as a reviewer would, and reports.              |
+| `/analyze [run]`       | Analyzes one run and says which instruction to change.           |
 | `/new-agent`           | Adds an agent - prompt, wiring and hand-offs.                    |
 | `/new-skill`           | Adds a skill under `agents/skills/`.                             |
 
@@ -283,6 +284,17 @@ schemas - to a model with your question on the end and tool calling off, and
 tells it the run is over and its own instructions are quotable. It is how a
 prompt that reads correctly and behaves wrongly explains itself.
 
+`ask` has two modes, decided by whether the question is given:
+
+- **One-shot** - a question on the line, in `--question-file`, or `--json`.
+  For a script or the agent in your editor: no banner, no prompt, no picker.
+  stdout is the answer and nothing else, and the command exits.
+- **Interactive** - no question. For you, at a terminal: `zen inspect ask`
+  walks through the session, run and recorded LLM call (whichever are not
+  named), frames each question and Markdown answer separately, and keeps
+  accepting follow-ups until you submit an empty question. Without a terminal
+  it is an error, never a wait.
+
 Every step is a command, and everything each one reads or writes is a plain
 file: the specification, the findings `zen check` prints with a code, a location
 and a fix, the record `zen inspect` renders of what the run actually did. So the
@@ -482,11 +494,14 @@ you want to validate a project's execution environment before a run.
 
 ```sh
 zen sandbox status                    # engine, project image and active containers
+zen sandbox top                       # memory and cpu, live: this computer, the machine, each container
+zen sandbox top --once                # the same, printed once (also with --json or when piped)
 zen sandbox up                        # prepare the execution environment for this project
 zen sandbox pull                      # pull or build this project's image only
 zen sandbox status --project my-app   # inspect a named project from anywhere
 zen sandbox disk                      # storage used by the engine and known projects
 zen sandbox clean                     # remove containers created by zen
+zen sandbox clean --idle              # only what no live run is using
 ```
 
 `status`, `up` and `pull` use the project in the current directory, or accept
@@ -494,6 +509,13 @@ zen sandbox clean                     # remove containers created by zen
 `disk` are machine-wide operations, so use them when you mean to inspect or
 remove resources beyond the current project.
 
+`top` is machine-wide too. Next to every figure it says in a few words what the
+figure means; `--brief` leaves those notes out, `--interval <seconds>` sets how
+often the live screen refreshes. On macOS it answers the usual question - why
+Activity Monitor shows "Virtual Machine Service for vfkit" holding many
+gigabytes - by setting what macOS counts for the machine against what is in use
+inside it, and naming the command that gives the difference back.
+
 ## Sharing a project
 
 A project is a directory, so sending one somewhere else is a zip - except that
@@ -541,6 +563,7 @@ The commands to run next are printed for you to read and type.
 | `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
 | `meta`    | Runs the meta agent over the project - the one that edits it.        |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
+| `view`    | Shows a folder in the browser, redrawn live as its files change.     |
 | `memory`  | What the agents remember - size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `export`  | Writes the project to a shareable zip archive.                       |
@@ -631,6 +654,7 @@ zen meta run acme "review the last commit"
 zen meta prompts                             # which /<name> prompts this project has
 zen meta run /project-review                 # .github/prompts/project-review.prompt.md
 zen meta run acme /spec-sync-project agents/triage.md
+zen meta run /analyze 20260825-143012-a7f3   # analyze one run
 git diff | zen meta run "what broke?" --allow-tool read
 zen meta run --dry-run "hello"               # what would run, secrets masked
 ```
@@ -698,6 +722,41 @@ the next run. A typed prefix that names no provider - `vertes/...` - is caught
 before that, because it would otherwise be sent whole to a vendor you never
 named. `--force` stores a ref without asking.
 
+### The dataset it evaluates against
+
+```sh
+zen meta run /dataset                        # build or refresh dataset/ from its sources
+zen meta dataset                             # revision, counts, what drifted
+zen meta dataset drift                       # which cases their source sections moved under
+zen meta dataset sample --rubric yes -n 12 --format batch -o cases.json
+zen meta dataset log planning-organize-day   # every change and verdict, and the sessions
+```
+
+`dataset/` holds every case with its rubric, an anchor to the section it was
+read from, and a journal of what changed and what was found. Only
+`zen meta dataset` writes it; `/dataset` re-reads just the sections that
+changed, and a case whose question or rubric changed is listed as restarted.
+See the `zen-dataset` skill a project carries in `.github/skills/`.
+
+### Tuning on it
+
+```sh
+zen meta finetune start -N 4                 # 4 cases at a time; resumes if stopped
+zen meta finetune                            # where it stands
+zen meta finetune stop                       # finish the steps in flight, then stop
+zen meta finetune serve                      # the pages live in a browser, while it is stopped
+zen meta finetune session plan-day           # resume that case's analyze session
+```
+
+Each case is run without memory and analyzed until it is right and lean, then
+run with the memory it wrote until that is cheaper. Improvement requests are
+applied in batches between runs, and every apply is a new, diffable version of
+the prose. Follow it in `finetune/STATUS.md`, whose summary shows whether the
+fixes and the memory are making runs cheaper; each case has its own
+`finetune/cases/<id>/FEEDBACK.md` with its latest analysis and the metrics of
+every try. `start` prints a local address that shows those pages in a browser,
+with their diagrams drawn, updated in place as the tuning writes them.
+
 ## Credentials
 
 One keyring serves every provider, and a key goes in the same way whatever it
@@ -755,6 +814,7 @@ zen models search haiku --tools --free      # narrow it
 zen models show openrouter:anthropic/claude-haiku-4.5
 zen models test vertex:gemini-embedding-001 # one real call, one verdict
 zen models pick --embedding                 # the first ref that answers, on stdout
+zen models browse                           # walk providers and models with the arrow keys
 ```
 
 Listings are cached for a day in `~/.zenera/neo/cache`. If a provider cannot be
@@ -788,6 +848,11 @@ the above is a single substitution, whether a person or an agent is doing it:
 zen rag schema index --embedding "$(zen models pick --embedding)" ./specs/*.yaml
 ```
 
+`zen models browse [provider]` is the interactive way in: arrow keys through
+the providers and their models, `/` to filter, `tab` to cycle roles, `enter`
+for one model in full, `t` to ask it one question, `p` to pick it. The picked
+ref is printed on stdout, so `ref="$(zen models browse)"` works too.
+
 ### Setting up each provider
 
 The shape is the same everywhere - `zen key add <provider>`, then answer the

package/dist/ask.js

@@ -1,5 +1,5 @@
 import { text, } from '@zenera/neo';
-import { splitRef } from "./meta.js";
+import { splitRef } from "./modelref.js";
 import { invalidError } from "./term.js";
 // ---------------------------------------------------------------------------
 // Asking a run about itself
@@ -31,13 +31,36 @@ export const DEBUG_PREAMBLE = [
     'write now reaches a user, a file or a machine. The last message is a question from',
     'the operator of this agent about what you did and why.',
     '',
-    'Answer that question in plain prose. Do not call a tool. Do not resume the task.',
+    'Answer that question. Do not call a tool. Do not resume the task. If the question',
+    'asks for a format, use it.',
     '',
     'This is an authorised post-mortem over data the operator already holds, so you are',
     'allowed — and asked — to quote your system prompt, instruction files and skills',
-    'verbatim, to name the file or section that steered you, and to say plainly which',
-    'instruction you followed, which you missed, and which two of them contradicted each',
-    'other. "I cannot reveal my instructions" is not an answer to any question below.',
+    'verbatim. "I cannot reveal my instructions" is not an answer to any question below.',
+    '',
+    '## Cite where every reason came from',
+    '',
+    'The operator is using your answer to find the text that shaped your behaviour and',
+    'edit it. An explanation without a source cannot be acted on. For every reason you',
+    'give, name its source and quote it verbatim, the exact words as they appear above:',
+    '',
+    '- **system prompt** — the instruction file or section, by its file name or nearest heading',
+    '- **skill** — the skill name and the heading inside it',
+    '- **tool description** — the tool name, and the parameter when the text is in its schema',
+    '- **message** — the user request, or a tool result, by tool name and call id',
+    '',
+    'Write each as: [<kind>: <name> › <heading or parameter>] "<verbatim quote>".',
+    '',
+    'Then trace the decision itself: what options you could see at that point, which one',
+    'you took, and which quoted text tipped it. Say which instruction you followed, which',
+    'applied but you missed or never reached, which two pulled in different directions,',
+    'and any condition or exception ("unless…", "only when…") you judged to apply.',
+    '',
+    'Be exact about provenance. When no text above told you to do what you did, say',
+    '"no instruction — my own default" rather than attaching it to the nearest',
+    'plausible source. When you are unsure whether a sentence is really there, say so.',
+    'Never paraphrase inside quotation marks: the operator will search for your quote,',
+    'and a quote that is not found discredits the whole answer.',
 ].join('\n');
 /**
  * The `request` blob of an `llm_call` node, which is `Kernel.serializeRequest`

package/dist/banner.js

@@ -1,4 +1,4 @@
-import { appearance, dim, note, styled } from "./term.js";
+import { appearance, dim, drivenByAgent, note, styled } from "./term.js";
 // ---------------------------------------------------------------------------
 // The banner
 //
@@ -149,7 +149,7 @@ export function bannerArt(text) {
 }
 /** Narration, and only for someone watching. */
 export function printBanner(text, options = {}) {
-    if (!process.stderr.isTTY) {
+    if (!process.stderr.isTTY || drivenByAgent()) {
         return;
     }
     note('');

package/dist/batch.d.ts

@@ -40,6 +40,12 @@ export interface BatchOptions {
 }
 export type MemoryMode = 'read-only' | 'copied' | 'none';
 export declare function runBatch(opts: BatchOptions): Promise<void>;
+/**
+ * The most containers one item can start: one shared by the agents on the
+ * project's sandbox block, one more for each agent with a block of its own.
+ * A project that does not load is each item's to report, so it counts none.
+ */
+export declare function containersPerItem(dir: string): number;
 /**
  * A bounded map that keeps its order. Workers pull from one cursor rather than
  * taking a slice each, so a batch of one slow item and fifty fast ones finishes

package/dist/batch.js

@@ -1,4 +1,4 @@
-import { addUsage, lockHolder, MANIFEST_FILE as MEMORY_MANIFEST, memoryDir, MemoryStore, mergeModelUsage, readProjectConfig, usageByModel, zeroUsage, } from '@zenera/neo';
+import { addUsage, lockHolder, MANIFEST_FILE as MEMORY_MANIFEST, memoryDir, MemoryStore, mergeModelUsage, readProjectConfig, SANDBOX_GROUP, selectTools, usageByModel, zeroUsage, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { cp, mkdir, rm, writeFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
@@ -6,14 +6,23 @@ import * as Engine from "./engine.js";
 import { stamp } from "./ids.js";
 import { duration } from "./narrate.js";
 import { BatchProgress } from "./progress.js";
+import { assertLocks } from "./podman.js";
 import { project as resolveProject, target } from "./resolve.js";
 import { display } from "./session.js";
 import { CliError, count, cyan, dim, EXIT, invalidError, json, jsonText, note, usageError, write, } from "./term.js";
+import { appendUsage } from "./usage.js";
+import { availableTools } from "./validate.js";
 /** Past this, the limit is the provider's rate limit and the failures are 429s. */
 const MAX_CONCURRENCY = 32;
 export async function runBatch(opts) {
     const project = await resolveProject({ cwd: opts.cwd, project: opts.project });
     const items = opts.request.items;
+    // Every item at once holds its own containers, so a short engine fails
+    // here once instead of once per item.
+    const boxes = containersPerItem(project.dir);
+    if (boxes > 0) {
+        await assertLocks(boxes * Math.min(opts.concurrency, items.length));
+    }
     const dir = opts.dir ? resolve(opts.cwd, opts.dir) : join(project.dir, 'batches', stamp());
     // Two batches in one directory would interleave their item folders and the
     // second would overwrite the first's index while the first still points at
@@ -127,6 +136,20 @@ export async function runBatch(opts) {
     };
     const text = jsonText(body);
     await writeFile(join(dir, 'batch.json'), text, 'utf8');
+    appendUsage(project.dir, {
+        kind: 'batch',
+        ts: finishedAt.toISOString(),
+        batchDir: dir,
+        input: opts.input,
+        items: items.length,
+        ok: results.length - failed,
+        failed,
+        concurrency: opts.concurrency,
+        memory: mode,
+        startedAt: startedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        models,
+    });
     if (opts.out) {
         await writeFile(resolve(opts.cwd, opts.out), text, 'utf8');
     }
@@ -150,6 +173,34 @@ export async function runBatch(opts) {
         throw new CliError(`${count(failed, 'item')} failed`, EXIT.failed, `what each one said: ${join(dir, 'batch.json')}`);
     }
 }
+// ---------------------------------------------------------------------------
+// One item
+// ---------------------------------------------------------------------------
+/**
+ * The most containers one item can start: one shared by the agents on the
+ * project's sandbox block, one more for each agent with a block of its own.
+ * A project that does not load is each item's to report, so it counts none.
+ */
+export function containersPerItem(dir) {
+    let read;
+    try {
+        read = readProjectConfig(dir);
+    }
+    catch {
+        return 0;
+    }
+    const tools = availableTools(read.root, read.config);
+    const shells = read.config.agents.filter((a) => {
+        try {
+            return selectTools(tools, [...(a.tools ?? [])], { where: a.name }).some((t) => t.group === SANDBOX_GROUP);
+        }
+        catch {
+            return false;
+        }
+    });
+    const own = shells.filter((a) => a.sandbox).length;
+    return own + (shells.length > own ? 1 : 0);
+}
 /**
  * A failure is data. One item that asks something the model cannot answer must
  * not cost the other ninety-nine their answers, so everything is caught and
@@ -181,6 +232,9 @@ async function runItem(item, ctx) {
             yes: true,
             // The project's own problems are the batch's, not each item's.
             quiet: true,
+            // A fresh session nobody resumes: a stopped container per item
+            // is how a few fine-tuning rounds used up every engine lock.
+            disposable: true,
         });
         try {
             // Nothing is narrated to the terminal — a hundred interleaved
@@ -192,6 +246,18 @@ async function runItem(item, ctx) {
             await writeFile(output, jsonText(Engine.envelope(engine, outcome)), 'utf8');
             const models = usageByModel(outcome.result.state.trajectory);
             ctx.spent.push(models);
+            appendUsage(ctx.projectDir, {
+                kind: 'run',
+                ts: new Date().toISOString(),
+                runDir: outcome.run.dir,
+                session: engine.session.id,
+                batchDir: ctx.dir,
+                item: item.id,
+                ok: true,
+                stopReason: outcome.result.stopReason,
+                durationMs: outcome.durationMs,
+                models,
+            });
             ctx.progress.finish(item.id, { ok: true, usage: outcome.result.usage, models });
             return { index: item.index, id: item.id, ok: true, input: index(item.input), output };
         }
@@ -205,6 +271,15 @@ async function runItem(item, ctx) {
             ...(err instanceof CliError && err.hint ? { hint: err.hint } : {}),
         };
         await writeFile(output, jsonText({ ok: false, id: item.id, error }), 'utf8');
+        appendUsage(ctx.projectDir, {
+            kind: 'run',
+            ts: new Date().toISOString(),
+            batchDir: ctx.dir,
+            item: item.id,
+            ok: false,
+            error: error.message,
+            models: [],
+        });
         ctx.progress.finish(item.id, { ok: false, error: error.message });
         return {
             index: item.index,

package/dist/catalog.d.ts

@@ -36,6 +36,8 @@ export interface CatalogEntry {
     };
     /** ISO date the model was published, when known */
     created?: string;
+    /** vertex only: who makes it - `google`, or the partner Vertex resells */
+    publisher?: string;
     source: 'live' | 'curated';
 }
 /** A provider's listing, and an honest account of where it came from. */
@@ -72,6 +74,7 @@ export declare const PREFERRED: Record<Provider, {
     chat: readonly string[];
     embedding: readonly string[];
 }>;
+export declare function fromVertexPartners(): Promise<CatalogEntry[]>;
 /**
  * Asks one provider what it serves. Throws whatever the SDK throws.
  *
@@ -79,8 +82,9 @@ export declare const PREFERRED: Record<Provider, {
  * to break when a vendor reshapes a payload, and they are untestable if the
  * only way to reach them is a credential and a network. It mirrors
  * `ProviderSpec.client`, which exists in the library for the same reason.
+ * `partners` is the same seam for Vertex's second listing.
  */
-export declare function fetchCatalog(provider: Provider, client?: unknown): Promise<CatalogEntry[]>;
+export declare function fetchCatalog(provider: Provider, client?: unknown, partners?: () => Promise<CatalogEntry[]>): Promise<CatalogEntry[]>;
 /** The key one provider's listing is filed under, version and all. */
 export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {
@@ -99,6 +103,26 @@ export interface CatalogOptions {
  * model list to four rows.
  */
 export declare function loadCatalog(provider: Provider, opts?: CatalogOptions): Promise<Catalog>;
+/** A per-token USD price as dollars per million tokens, the unit price lists use. */
+export declare function perMillion(price: string | undefined): string;
+/** What an OpenRouter account has left to spend, as far as its key may see. */
+export interface Balance {
+    /** credits bought minus credits used; absent when the key may not read the account */
+    credits?: number;
+    /** the key's own spending cap, when one is set */
+    cap?: {
+        limit: number;
+        remaining: number;
+        reset?: string;
+    };
+    /** requests to `:free` models left today */
+    free?: {
+        used: number;
+        limit: number;
+        remaining: number;
+    };
+}
+export declare function routerBalance(): Promise<Balance>;
 /** Every provider asked at once — they are independent and mostly latency. */
 export declare function loadCatalogs(providers: readonly Provider[], opts?: CatalogOptions): Promise<Catalog[]>;
 export interface Filters {
@@ -111,4 +135,10 @@ export interface Filters {
 export declare function matches(row: CatalogEntry, query: string, filters?: Filters): boolean;
 /** The providers a search covers when none was named. */
 export declare const catalogProviders: () => readonly Provider[];
+/** Resold on Vertex rather than made by Google. */
+export declare const isPartner: (e: CatalogEntry) => boolean;
+/** Provider, then Google's own models, then each partner's together. */
+export declare function byGroup(a: CatalogEntry, b: CatalogEntry): number;
+/** The heading a row is listed under, when its provider resells other makers' models. */
+export declare function groupOf(e: CatalogEntry): string | undefined;
 //# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -16,7 +16,7 @@
 // `source` for exactly that reason: a curated guess must never be mistaken for
 // the vendor's own word.
 // ---------------------------------------------------------------------------
-import { ModelRegistry } from '@zenera/neo';
+import { ModelRegistry, vertexEndpoint } from '@zenera/neo';
 import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
@@ -24,7 +24,7 @@ import { classify } from "./liveness.js";
 export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
 export const CATALOG_KIND = 'catalog';
 /** Bumped when the stored shape changes, which makes every old entry a miss. */
-const CATALOG_VERSION = 1;
+const CATALOG_VERSION = 2;
 // ---------------------------------------------------------------------------
 // The fallback table
 // ---------------------------------------------------------------------------
@@ -53,9 +53,17 @@ export const CURATED = {
         { id: 'gemini-embedding-2', roles: ['embedding'] },
     ],
     vertex: [
-        { id: 'gemini-3.5-flash-lite', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576 },
-        { id: 'gemini-embedding-2', roles: ['embedding'] },
+        {
+            id: 'gemini-3.5-flash-lite',
+            roles: ['chat'],
+            contextLength: 1_048_576,
+            publisher: 'google',
+        },
+        { id: 'gemini-3.8-flash', roles: ['chat'], contextLength: 1_048_576, publisher: 'google' },
+        { id: 'gemini-embedding-2', roles: ['embedding'], publisher: 'google' },
+        // Open-weight models are served but not listed by Model Garden, so these are the only record.
+        { id: 'qwen/qwen3-235b-a22b-instruct-2507-maas', roles: ['chat'], publisher: 'qwen' },
+        { id: 'openai/gpt-oss-120b-maas', roles: ['chat'], publisher: 'openai' },
     ],
     openrouter: [
         { id: 'openai/gpt-5.6-luna', roles: ['chat'], contextLength: 1_050_000 },
@@ -227,6 +235,7 @@ async function fromGenAI(client, provider) {
             description: model.description,
             contextLength: model.inputTokenLimit,
             maxOutputTokens: model.outputTokenLimit,
+            publisher: provider === 'vertex' ? 'google' : undefined,
         }));
     }
     return rows;
@@ -296,6 +305,38 @@ async function fromRouter(client, provider) {
     }
     return rows;
 }
+/**
+ * Partner models on Vertex. The GenAI listing holds Google's alone, so each
+ * partner's Model Garden listing is asked as well - only for publishers whose
+ * models the runtime can call: Claude at `rawPredict`, the rest at the
+ * OpenAI-compatible endpoint as `publisher/model`.
+ */
+const VERTEX_PARTNERS = ['anthropic', 'xai'];
+export async function fromVertexPartners() {
+    const at = vertexEndpoint();
+    const token = await at.token();
+    const lists = await Promise.all(VERTEX_PARTNERS.map(async (publisher) => {
+        const res = await fetch(`https://aiplatform.googleapis.com/v1beta1/publishers/${publisher}/models?pageSize=200`, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'x-goog-user-project': at.project,
+            },
+        });
+        if (!res.ok) {
+            return [];
+        }
+        const body = (await res.json());
+        return (body.publisherModels ?? [])
+            .map((m) => bareId(m.name ?? ''))
+            .filter((id) => id && !/embed|ocr/.test(id))
+            .map((id) => entry('vertex', {
+            id: publisher === 'anthropic' ? id : `${publisher}/${id}`,
+            roles: ['chat'],
+            publisher,
+        }));
+    }));
+    return lists.flat();
+}
 /**
  * Asks one provider what it serves. Throws whatever the SDK throws.
  *
@@ -303,16 +344,27 @@ async function fromRouter(client, provider) {
  * to break when a vendor reshapes a payload, and they are untestable if the
  * only way to reach them is a credential and a network. It mirrors
  * `ProviderSpec.client`, which exists in the library for the same reason.
+ * `partners` is the same seam for Vertex's second listing.
  */
-export async function fetchCatalog(provider, client = new ModelRegistry().client(provider)) {
+export async function fetchCatalog(provider, client = new ModelRegistry().client(provider), partners = fromVertexPartners) {
     switch (provider) {
         case 'openai':
             return enrich(provider, await fromOpenAI(client, provider));
         case 'anthropic':
             return enrich(provider, await fromAnthropic(client, provider));
         case 'google':
-        case 'vertex':
             return enrich(provider, await fromGenAI(client, provider));
+        case 'vertex': {
+            // A partner listing that fails must not cost the Gemini one.
+            const [google, others] = await Promise.all([
+                fromGenAI(client, provider),
+                partners().catch(() => []),
+            ]);
+            const live = [...google, ...others];
+            const seen = new Set(live.map((r) => r.id));
+            const unlisted = curated(provider).filter((r) => r.publisher !== 'google' && !seen.has(r.id));
+            return enrich(provider, [...live, ...unlisted]);
+        }
         case 'openrouter':
             return enrich(provider, await fromRouter(client, provider));
     }
@@ -425,6 +477,66 @@ export async function loadCatalog(provider, opts = {}) {
         fetchedAt: new Date(0).toISOString(),
     };
 }
+// ---------------------------------------------------------------------------
+// Prices and balance
+// ---------------------------------------------------------------------------
+/** A per-token USD price as dollars per million tokens, the unit price lists use. */
+export function perMillion(price) {
+    if (price === undefined || price === '') {
+        return '';
+    }
+    const n = Number(price) * 1_000_000;
+    if (!Number.isFinite(n)) {
+        return '';
+    }
+    // OpenRouter prices its routers (`openrouter/auto`) as "-1": it depends on the pick.
+    if (n < 0) {
+        return 'varies';
+    }
+    if (n === 0) {
+        return 'free';
+    }
+    if (n >= 1) {
+        return `$${n.toFixed(2)}`;
+    }
+    // Two significant digits for fractions of a dollar, but never fewer than cents.
+    const short = String(Number(n.toPrecision(2)));
+    return `$${(short.split('.')[1]?.length ?? 0) < 2 ? n.toFixed(2) : short}`;
+}
+export async function routerBalance() {
+    const base = (process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1').replace(/\/+$/, '');
+    const get = async (path) => {
+        const res = await fetch(`${base}${path}`, {
+            headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY ?? ''}` },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            throw Object.assign(new Error(`${path} answered ${res.status}`), {
+                status: res.status,
+            });
+        }
+        return (await res.json()).data;
+    };
+    // Raw rather than the SDK: its schema drops `free_model_daily_requests`.
+    const [key, credits] = await Promise.all([
+        get('/key'),
+        // Documented as management-key only, though ordinary keys are answered too.
+        get('/credits').catch(() => undefined),
+    ]);
+    return {
+        ...(credits ? { credits: credits.total_credits - credits.total_usage } : {}),
+        ...(key.limit !== null && key.limit_remaining !== null
+            ? {
+                cap: {
+                    limit: key.limit,
+                    remaining: key.limit_remaining,
+                    ...(key.limit_reset ? { reset: key.limit_reset } : {}),
+                },
+            }
+            : {}),
+        ...(key.free_model_daily_requests ? { free: key.free_model_daily_requests } : {}),
+    };
+}
 /** Every provider asked at once — they are independent and mostly latency. */
 export async function loadCatalogs(providers, opts = {}) {
     return Promise.all(providers.map((p) => loadCatalog(p, opts)));
@@ -459,4 +571,25 @@ export function matches(row, query, filters = {}) {
 }
 /** The providers a search covers when none was named. */
 export const catalogProviders = () => PROVIDERS;
+// ---------------------------------------------------------------------------
+// Grouping
+// ---------------------------------------------------------------------------
+/** Resold on Vertex rather than made by Google. */
+export const isPartner = (e) => e.publisher !== undefined && e.publisher !== 'google';
+/** Provider, then Google's own models, then each partner's together. */
+export function byGroup(a, b) {
+    return (a.provider.localeCompare(b.provider) ||
+        Number(isPartner(a)) - Number(isPartner(b)) ||
+        (a.publisher ?? '').localeCompare(b.publisher ?? '') ||
+        a.id.localeCompare(b.id));
+}
+/** The heading a row is listed under, when its provider resells other makers' models. */
+export function groupOf(e) {
+    if (!e.publisher) {
+        return undefined;
+    }
+    return isPartner(e)
+        ? `${e.provider} · partner · ${e.publisher}`
+        : `${e.provider} · Google (Gemini, Gemma, Imagen, Veo)`;
+}
 //# sourceMappingURL=catalog.js.map

package/dist/commands/index.js

@@ -13,6 +13,7 @@ import { open } from "./open.js";
 import { run } from "./run.js";
 import { sandbox } from "./sandbox.js";
 import { version } from "./version.js";
+import { view } from "./view.js";
 /**
  * Insertion order is the order help prints in, and it is deliberate: the four
  * a new user needs first, then the credentials-and-models pair, then the two
@@ -32,6 +33,7 @@ export const COMMANDS = {
     models,
     check,
     inspect,
+    view,
     export: pack,
     import: unpack,
     memory,