nylorun 0.13.0-beta → 0.15.0-beta

package/dist/client/io.js

@@ -0,0 +1,72 @@
+/**
+ * What the `tenant` commands read and print: a JSON body from a file or standard input (`-`),
+ * checked against the request's schema before anything is sent; a secret from standard input,
+ * never from the arguments; and tables.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { CliError } from "../errors.js";
+const usageError = (message) => new CliError(message, 2);
+/** Standard input as text; a usage error when it is a terminal or there is none. */
+async function readStdin(deps, refusal) {
+    if (!deps.stdin || deps.stdin.isTTY)
+        throw usageError(refusal);
+    return await deps.stdin.text();
+}
+/**
+ * The JSON body in file `source`, or on standard input for `-`, as `schema` parses it. Fields
+ * named in `readOnly` (a view's, so a `get` can be edited and put back) are dropped first. A
+ * body that does not parse is a usage error, before any request.
+ */
+export async function readBody(deps, source, schema, readOnly = []) {
+    let text;
+    if (source === "-") {
+        text = await readStdin(deps, "Pipe the JSON body in on standard input, or name a file.");
+    }
+    else {
+        try {
+            text = await readFile(resolve(deps.cwd ?? process.cwd(), source), "utf8");
+        }
+        catch (error) {
+            throw usageError(`Cannot read ${source}: ${error.code ?? error}.`);
+        }
+    }
+    const where = source === "-" ? "Standard input" : source;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw usageError(`${where} is not JSON: ${error.message}.`);
+    }
+    if (value && typeof value === "object" && !Array.isArray(value))
+        value = Object.fromEntries(Object.entries(value).filter(([key]) => !readOnly.includes(key)));
+    const parsed = schema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    const issues = parsed.error.issues.map((issue) => `  ${issue.path.length ? `${issue.path.map(String).join(".")}: ` : ""}${issue.message}`);
+    throw usageError(`${where} is not a valid body:\n${issues.join("\n")}`);
+}
+/**
+ * A secret piped in on standard input (its trailing newline dropped), so it is never in the
+ * arguments, the shell's history or the process list. `what` names it in the refusals.
+ */
+export async function readSecret(deps, what, example) {
+    const secret = (await readStdin(deps, `Pipe the ${what} in on standard input, for example: ${example}. It is never taken as an argument.`)).trim();
+    if (!secret)
+        throw usageError(`Standard input held no ${what}.`);
+    return secret;
+}
+/** `rows` (the first is the header) as columns two spaces apart, with no trailing blanks. */
+export function printTable(deps, rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+    for (const row of rows)
+        deps.out(row
+            .map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column])))
+            .join("  ")
+            .trimEnd());
+}
+/** `value` as indented JSON on stdout. */
+export function printJson(deps, value) {
+    deps.out(JSON.stringify(value, null, 2));
+}

package/dist/client/mcp.d.ts

@@ -0,0 +1,11 @@
+import type { McpPreview } from "@nylorun/core/contracts";
+import { type StackDeps } from "../stack/commands.js";
+export declare const mcpUsage = "  mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]\n                                      list a remote MCP server's tools, with Environment <id>'s\n                                      credential for <url> (none without it): model names, schema\n                                      sizes, renames, or that it needs a person's sign-in (the\n                                      Runtime calls no tool)";
+/** What `--vault` says since protocol 11. */
+export declare const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Environment, in its own vault. Pass --environment <id> to send that Environment's credential for the URL.";
+/** What the removed `connect` subcommand says since protocol 10. */
+export declare const MCP_CONNECT_REMOVED: string;
+/** A preview as a person reads it: the server, a table of tools, the renames, or the sign-in hint. */
+export declare function previewLines(preview: McpPreview, environmentId?: string): string[];
+/** `nylorun tenant mcp <inspect|connect> ...` */
+export declare function mcpCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/{stack → client}/mcp.js

@@ -1,34 +1,45 @@
 /**
- * `nylorun mcp inspect <url>`: a remote MCP server's tools before an agent names it (R2b C12),
- * through the running local Tenant's Management API (`POST /v1/tenant/mcp/preview`) with the
- * Project link's management key, else the Host root's (`runningTenantApi`). It never starts the
- * Tenant, and the Runtime never calls a tool. Its `connect` subcommand (MCP OAuth) was removed
- * in protocol 10, and says so.
+ * `nylorun tenant mcp inspect <url>`: a remote MCP server's tools before an agent names it (R2b
+ * C12), through the Management API (`POST /v1/tenant/mcp/preview`) of the installation
+ * `target.ts` picks. It never starts a local Tenant, and the Runtime never calls a tool. `--environment <id>` sends that Environment's
+ * credential for the URL (protocol 11; it replaced `--vault`); an Environment's secrets are
+ * written on the Runtime API (`client.environments.secrets.put` of `@nylorun/agents`). Its
+ * `connect` subcommand (MCP OAuth) was removed in protocol 10, and says so.
  */
 import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
 import { CliError } from "../errors.js";
-import { parseStackFlags, runningTenantApi } from "./commands.js";
-export const mcpUsage = `  mcp inspect <url> [--server <name>] [--vault <id>] [--sse] [--tenant <name>] [--json]
-                                      list a remote MCP server's tools with the installation vault's
-                                      credential for <url>: model names, schema sizes, renames, or
-                                      that it needs a person's sign-in (the Runtime calls no tool)`;
-const INSPECT_USAGE = "nylorun mcp inspect <url> [--server <name>] [--vault <id>] [--sse] [--tenant <name>] [--json]";
+import { parseStackFlags } from "../stack/commands.js";
+import { connect } from "./target.js";
+export const mcpUsage = `  mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]
+                                      list a remote MCP server's tools, with Environment <id>'s
+                                      credential for <url> (none without it): model names, schema
+                                      sizes, renames, or that it needs a person's sign-in (the
+                                      Runtime calls no tool)`;
+const INSPECT_USAGE = "nylorun tenant mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]";
+/** Where a credential for an MCP server goes since protocol 11. */
+const SECRET_HINT = "write it as a bearer or headers secret of an Environment (nylorun environments secrets put, client.environments.secrets.put of @nylorun/agents, or Studio)";
+/** What `--vault` says since protocol 11. */
+export const MCP_VAULT_REMOVED = "--vault was removed in protocol 11: a credential is a secret of an Environment, in its own vault. Pass --environment <id> to send that Environment's credential for the URL.";
 /** What the removed `connect` subcommand says since protocol 10. */
-export const MCP_CONNECT_REMOVED = "The connect subcommand of nylorun mcp was removed with MCP OAuth (protocol 10): add the server's key to an installation vault as a bearer or headers credential (Studio's Credentials page, or @nylorun/admin), or reach a server that needs a person's sign-in through a gateway (a credential with via). See its tools with nylorun mcp inspect <url>.";
+export const MCP_CONNECT_REMOVED = `The connect subcommand of nylorun mcp was removed with MCP OAuth (protocol 10): ${SECRET_HINT.replace("write it", "write the server's key")}, or reach a server that needs a person's sign-in through a gateway (a secret with via). See its tools with nylorun tenant mcp inspect <url> --environment <id>.`;
 /** The preview takes up to 15 s in the Runtime; the hop gets a margin. */
 const PREVIEW_TIMEOUT_MS = 30_000;
 const DESCRIPTION_CHARS = 60;
 const usageError = (message) => new CliError(message, 2);
 async function inspect(deps, args) {
-    const flags = parseStackFlags(args, { booleans: ["--json", "--sse"], values: ["--server", "--vault", "--tenant"] }, INSPECT_USAGE);
+    if (args.some((arg) => arg === "--vault" || arg.startsWith("--vault=")))
+        throw usageError(MCP_VAULT_REMOVED);
+    const flags = parseStackFlags(args, { booleans: ["--json", "--sse"], values: ["--server", "--environment", "--tenant"] }, INSPECT_USAGE);
     if (flags.rest.length !== 1)
         throw usageError(`Usage: ${INSPECT_USAGE}`);
     const url = flags.rest[0];
     const name = flags.values.get("--server");
-    const vaultId = flags.values.get("--vault");
+    const environmentId = flags.values.get("--environment");
     const tenant = flags.values.get("--tenant");
-    const api = await runningTenantApi(deps, tenant === undefined ? {} : { name: tenant });
-    const response = await deps.fetch(`${api.runtimeUrl}/v1/tenant/mcp/preview`, {
+    const api = await connect(deps, "management", tenant);
+    if (!api.managementKey)
+        throw new CliError(`No management key for ${api.label}: set NYLORUN_MANAGEMENT_KEY.`, 1);
+    const response = await deps.fetch(`${api.url}/v1/tenant/mcp/preview`, {
         method: "POST",
         headers: {
             authorization: `Bearer ${api.managementKey}`,
@@ -40,14 +51,14 @@ async function inspect(deps, args) {
             url,
             ...(flags.booleans.has("--sse") ? { type: "sse" } : {}),
             ...(name === undefined ? {} : { name }),
-            ...(vaultId === undefined ? {} : { vaultId }),
+            ...(environmentId === undefined ? {} : { environmentId }),
         }),
         redirect: "error",
         signal: AbortSignal.timeout(PREVIEW_TIMEOUT_MS),
     });
     const body = (await response.json().catch(() => ({})));
     if (response.status === 404 && body.code === "not_found")
-        throw new CliError(`Tenant ${api.name} runs a Runtime without MCP previews. Update it: npx nylorun@latest start.`, 1);
+        throw new CliError(`${api.label} runs a Runtime without MCP previews. Update it.`, 1);
     if (!response.ok) {
         const details = body.details;
         const failure = typeof details?.failure === "string" ? ` (${details.failure})` : "";
@@ -60,15 +71,17 @@ async function inspect(deps, args) {
         deps.out(JSON.stringify(preview, null, 2));
         return 0;
     }
-    for (const line of previewLines(preview))
+    for (const line of previewLines(preview, environmentId))
         deps.out(line);
     return 0;
 }
 /** A preview as a person reads it: the server, a table of tools, the renames, or the sign-in hint. */
-export function previewLines(preview) {
+export function previewLines(preview, environmentId) {
     const credential = preview.credentialSent
-        ? "with the installation vault's credential"
-        : "with no credential (no installation vault holds one for this URL)";
+        ? `with Environment ${environmentId ?? "(unnamed)"}'s credential`
+        : environmentId === undefined
+            ? "with no credential (pass --environment <id> to send an Environment's)"
+            : `with no credential (Environment ${environmentId} holds none for this URL)`;
     if (preview.authRequired) {
         const metadata = preview.authRequired.resourceMetadata;
         const servers = Array.isArray(metadata?.authorization_servers)
@@ -76,13 +89,14 @@ export function previewLines(preview) {
             : [];
         return [
             preview.credentialSent
-                ? `The MCP server at ${preview.url} answered 401: it rejected the installation vault's credential.`
+                ? `The MCP server at ${preview.url} answered 401: it rejected Environment ${environmentId ?? "(unnamed)"}'s credential.`
                 : `The MCP server at ${preview.url} answered 401: it needs a credential.`,
             ...(servers.length > 0
                 ? [`It signs people in with ${servers.join(", ")} (${preview.authRequired.resourceMetadataUrl}).`]
                 : []),
-            "Nylorun holds no OAuth client: add the server's API key to an installation vault, or reach it",
-            "through a gateway that keeps each person's sign-in (a credential with via and an identity header).",
+            `Nylorun holds no OAuth client: ${SECRET_HINT.replace("write it", "write the server's API key")},`,
+            "and pass --environment <id>; or reach it through a gateway that keeps each person's sign-in",
+            "(a secret with via and an identity header).",
         ];
     }
     const info = preview.serverInfo;
@@ -131,7 +145,7 @@ function oneLine(text) {
     const flat = text.replace(/\s+/g, " ").trim();
     return flat.length > DESCRIPTION_CHARS ? `${flat.slice(0, DESCRIPTION_CHARS - 1)}…` : flat;
 }
-/** `nylorun mcp <inspect|connect> ...` */
+/** `nylorun tenant mcp <inspect|connect> ...` */
 export async function mcpCommand(deps, args) {
     const [sub, ...rest] = args;
     if (sub === "inspect")

package/dist/client/model/pi-ai.d.ts

@@ -1,9 +1,9 @@
 /**
- * The pi-ai `nylo configure` loads; nylorun's devDependency has the same version
+ * The pi-ai `nylorun tenant models set` loads; nylorun's devDependency has the same version
  * (scripts/check-package.mjs).
  */
 export declare const PI_AI_VERSION = "0.99.1";
-/** What `nylo configure` uses of pi-ai: its provider registry and login flows. */
+/** What `nylorun tenant models set` uses of pi-ai: its provider registry and login flows. */
 export interface PiAi {
     createProvider: typeof import("@earendil-works/pi-ai").createProvider;
     builtinModels: typeof import("@earendil-works/pi-ai/providers/all").builtinModels;
@@ -12,7 +12,7 @@ export interface PiAi {
 }
 /**
  * pi-ai, with its provider SDKs about 100 MB, is not a dependency of nylorun, so
- * `npx nylorun` stays small: only `nylo configure` needs it. It loads pi-ai from beside nylorun
+ * `npx nylorun` stays small: only `nylorun tenant models set` needs it. It loads pi-ai from beside nylorun
  * when it resolves there (the workspace, or a project that installs it), else from
  * `<Nylorun home>/lib/pi-ai-<version>/`, which it installs with npm on first use.
  */

package/dist/client/model/pi-ai.js

@@ -7,7 +7,7 @@ import { pathToFileURL } from "node:url";
 import { nylorunHome } from "@nylorun/core/project";
 import { CliError } from "../../errors.js";
 /**
- * The pi-ai `nylo configure` loads; nylorun's devDependency has the same version
+ * The pi-ai `nylorun tenant models set` loads; nylorun's devDependency has the same version
  * (scripts/check-package.mjs).
  */
 export const PI_AI_VERSION = "0.99.1";
@@ -35,7 +35,7 @@ const notInstalled = (error) => error?.code === "ERR_MODULE_NOT_FOUND" &&
     String(error.message).includes(`'${PI_AI}'`);
 /**
  * pi-ai, with its provider SDKs about 100 MB, is not a dependency of nylorun, so
- * `npx nylorun` stays small: only `nylo configure` needs it. It loads pi-ai from beside nylorun
+ * `npx nylorun` stays small: only `nylorun tenant models set` needs it. It loads pi-ai from beside nylorun
  * when it resolves there (the workspace, or a project that installs it), else from
  * `<Nylorun home>/lib/pi-ai-<version>/`, which it installs with npm on first use.
  */
@@ -49,7 +49,7 @@ export async function loadPiAi(options = {}) {
     }
     const directory = join(nylorunHome(options.home), "lib", `pi-ai-${PI_AI_VERSION}`);
     if (!existsSync(join(directory, ENTRY))) {
-        (options.log ?? ((line) => console.error(line)))(`nylo configure uses ${PI_AI}@${PI_AI_VERSION} for the model providers' sign-in, which nylorun does not install. Installing it once into ${directory}…`);
+        (options.log ?? ((line) => console.error(line)))(`nylorun tenant models set uses ${PI_AI}@${PI_AI_VERSION} for the model providers' sign-in, which nylorun does not install. Installing it once into ${directory}…`);
         await installInto(directory, options.install ?? npmInstall);
     }
     return (await import(pathToFileURL(join(directory, ENTRY)).href));
@@ -68,7 +68,7 @@ async function installInto(directory, install) {
         });
     }
     catch (error) {
-        throw new CliError(`Could not install ${PI_AI}@${PI_AI_VERSION} for nylo configure: ${error instanceof Error ? error.message : String(error)}. Install it beside nylorun (npm install ${PI_AI}@${PI_AI_VERSION}), or set the model provider in Studio.`, 1);
+        throw new CliError(`Could not install ${PI_AI}@${PI_AI_VERSION} for nylorun tenant models set: ${error instanceof Error ? error.message : String(error)}. Install it beside nylorun (npm install ${PI_AI}@${PI_AI_VERSION}), or set the model provider in Studio.`, 1);
     }
     finally {
         await rm(temporary, { recursive: true, force: true });

package/dist/client/models.d.ts

@@ -0,0 +1,13 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const modelsUsage = "  models catalog [--tenant <name>] [--json]\n                                      every provider and model the Runtime knows\n  models providers [--tenant <name>] [--json]\n                                      the providers with a credential, and the one in use\n  models get [--tenant <name>] [--json]\n                                      the Tenant's model\n  models set [--tenant <name>]        sign in to a model provider and set the Tenant's model\n  models set --provider <id> --model <id> [--base-url <url>] [--tenant <name>]\n                                      the same with an API key piped in on stdin (CI)\n  models select <provider> [--model <id>] [--tenant <name>]\n                                      use a provider that has a credential (default: its model)";
+export declare const usageUsage = "  usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]\n                                      what the model calls used and cost (JSON)\n  calls [--after <cursor>] [--limit <n>] [--tenant <name>]\n                                      every recorded model call, one JSON line each, until\n                                      caught up; prints the cursor to resume from on stderr";
+/** `nylorun tenant models <verb> ...` */
+export declare function modelsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/** `nylorun tenant usage`: one scope's totals for one period, as JSON. */
+export declare function usageCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/**
+ * `nylorun tenant calls`: every recorded model call from `--after`, one JSON object per line
+ * (NDJSON) on stdout, page by page (`--limit` a page) until caught up; then the cursor to resume
+ * from on stderr. Rows may repeat across runs: deduplicate by id.
+ */
+export declare function callsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/models.js

@@ -0,0 +1,203 @@
+/**
+ * `nylorun tenant models | usage | calls`: the Tenant's model, what its model calls used, and the
+ * calls themselves, through the Management API. `models set` signs in with pi-ai (loaded only
+ * there) at a terminal; with `--provider` and `--model` it takes an API key piped in instead,
+ * for CI. A key is never an argument.
+ */
+import { randomUUID } from "node:crypto";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { printJson, printTable, readSecret } from "./io.js";
+import { connect, managementClient } from "./target.js";
+export const modelsUsage = `  models catalog [--tenant <name>] [--json]
+                                      every provider and model the Runtime knows
+  models providers [--tenant <name>] [--json]
+                                      the providers with a credential, and the one in use
+  models get [--tenant <name>] [--json]
+                                      the Tenant's model
+  models set [--tenant <name>]        sign in to a model provider and set the Tenant's model
+  models set --provider <id> --model <id> [--base-url <url>] [--tenant <name>]
+                                      the same with an API key piped in on stdin (CI)
+  models select <provider> [--model <id>] [--tenant <name>]
+                                      use a provider that has a credential (default: its model)`;
+export const usageUsage = `  usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]
+                                      what the model calls used and cost (JSON)
+  calls [--after <cursor>] [--limit <n>] [--tenant <name>]
+                                      every recorded model call, one JSON line each, until
+                                      caught up; prints the cursor to resume from on stderr`;
+const usageError = (message = `Usage:\n${modelsUsage}`) => new CliError(message, 2);
+async function client(deps, tenant) {
+    return managementClient(deps, await connect(deps, "management", tenant));
+}
+/** The Tenant's model in one line. */
+function describe(view) {
+    if (!view.configured)
+        return "No model is set: run nylorun tenant models set.";
+    return [view.provider, view.model, view.authType, ...(view.baseUrl ? [view.baseUrl] : [])].join("  ");
+}
+/** `models catalog | providers | get`: a table or a line, else `--json`. */
+async function read(deps, verb, args) {
+    const usage = `nylorun tenant models ${verb} [--tenant <name>] [--json]`;
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant"] }, usage);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${usage}`);
+    const admin = await client(deps, flags.values.get("--tenant"));
+    const json = flags.booleans.has("--json");
+    if (verb === "catalog") {
+        const catalog = await admin.models.catalog();
+        if (json)
+            printJson(deps, catalog);
+        else
+            printTable(deps, [
+                ["PROVIDER", "MODEL", "READS"],
+                ...catalog.providers.flatMap((provider) => provider.models.map((model) => [provider.id, model.id, model.inputs.join(",")])),
+            ]);
+    }
+    else if (verb === "providers") {
+        const { providers } = await admin.models.providers();
+        if (json)
+            printJson(deps, providers);
+        else if (!providers.length)
+            deps.err("No provider has a credential: run nylorun tenant models set.");
+        else
+            printTable(deps, [
+                ["PROVIDER", "MODEL", "AUTH", "IN USE"],
+                ...providers.map((p) => [p.id, p.model, p.authType, p.active ? "yes" : ""]),
+            ]);
+    }
+    else {
+        const view = await admin.models.get();
+        if (json)
+            printJson(deps, view);
+        else
+            deps.out(describe(view));
+    }
+    return 0;
+}
+const SET_USAGE = "nylorun tenant models set [--tenant <name>] | nylorun tenant models set --provider <id> --model <id> [--base-url <url>] [--tenant <name>]";
+/**
+ * `models set`: at a terminal, the sign-in prompts; with `--provider` and `--model`, the API key
+ * on stdin, set as `PUT /v1/tenant/model` with an `api_key` credential (OAuth needs the prompts).
+ */
+async function set(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--tenant", "--provider", "--model", "--base-url"] }, SET_USAGE);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${SET_USAGE}`);
+    const provider = flags.values.get("--provider");
+    const model = flags.values.get("--model");
+    const baseUrl = flags.values.get("--base-url");
+    if (provider !== undefined || model !== undefined || baseUrl !== undefined) {
+        if (provider === undefined || model === undefined)
+            throw usageError(`Pass both --provider and --model. Usage: ${SET_USAGE}`);
+        const key = await readSecret(deps, "API key", `printenv OPENAI_API_KEY | nylorun tenant models set --provider ${provider} --model ${model}`);
+        const admin = await client(deps, flags.values.get("--tenant"));
+        const view = await admin.models.put({
+            idempotencyKey: randomUUID(),
+            provider,
+            model,
+            ...(baseUrl ? { baseUrl } : {}),
+            auth: { type: "api_key", key },
+        });
+        deps.out(describe(view));
+        return 0;
+    }
+    const admin = await client(deps, flags.values.get("--tenant"));
+    const { ConfigurationCancelled, configureProvider, fetchModelCatalog } = await import("./model/configure.js");
+    const { putHostModel } = await import("./model/host-model.js");
+    const controller = new AbortController();
+    const cancel = (signal) => controller.abort(new ConfigurationCancelled(signal));
+    process.once("SIGINT", () => cancel("SIGINT"));
+    process.once("SIGTERM", () => cancel("SIGTERM"));
+    const catalog = await fetchModelCatalog(admin);
+    const prompted = await configureProvider({ signal: controller.signal, catalog });
+    await putHostModel(admin, prompted);
+    return 0;
+}
+/**
+ * `models select <provider>`: the provider's stored model and endpoint unless `--model` says
+ * otherwise (the Runtime keeps only the endpoint the request names).
+ */
+async function select(deps, args) {
+    const usage = "nylorun tenant models select <provider> [--model <id>] [--tenant <name>]";
+    const flags = parseStackFlags(args, { values: ["--tenant", "--model"] }, usage);
+    if (flags.rest.length !== 1)
+        throw usageError(`Usage: ${usage}`);
+    const id = flags.rest[0];
+    const admin = await client(deps, flags.values.get("--tenant"));
+    const stored = (await admin.models.providers()).providers.find((p) => p.id === id);
+    if (!stored)
+        throw new CliError(`Provider ${id} has no credential: run nylorun tenant models set (nylorun tenant models providers lists those that do).`, 1);
+    const view = await admin.models.select({
+        idempotencyKey: randomUUID(),
+        provider: id,
+        model: flags.values.get("--model") ?? stored.model,
+        ...(stored.baseUrl ? { baseUrl: stored.baseUrl } : {}),
+    });
+    deps.out(describe(view));
+    return 0;
+}
+/** `nylorun tenant models <verb> ...` */
+export async function modelsCommand(deps, args) {
+    const [verb, ...rest] = args;
+    if (verb === "catalog" || verb === "providers" || verb === "get")
+        return read(deps, verb, rest);
+    if (verb === "set")
+        return set(deps, rest);
+    if (verb === "select")
+        return select(deps, rest);
+    throw usageError();
+}
+const SCOPES = ["tenant", "agent", "turn"];
+const PERIODS = ["day", "month", "total"];
+const USAGE_USAGE = "nylorun tenant usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]";
+/** `nylorun tenant usage`: one scope's totals for one period, as JSON. */
+export async function usageCommand(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--tenant", "--scope", "--id", "--period"] }, USAGE_USAGE);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${USAGE_USAGE}`);
+    const scope = flags.values.get("--scope") ?? "tenant";
+    const period = flags.values.get("--period") ?? "total";
+    const id = flags.values.get("--id");
+    if (!SCOPES.includes(scope))
+        throw usageError(`--scope is one of ${SCOPES.join(", ")}.`);
+    if (!PERIODS.includes(period))
+        throw usageError(`--period is one of ${PERIODS.join(", ")}.`);
+    if ((scope === "tenant") !== (id === undefined))
+        throw usageError(scope === "tenant" ? "--id names an agent or a turn: pass --scope agent or turn." : `--scope ${scope} needs --id.`);
+    const query = {
+        scope: scope,
+        period: period,
+        ...(id === undefined ? {} : { id }),
+    };
+    printJson(deps, await (await client(deps, flags.values.get("--tenant"))).models.usage(query));
+    return 0;
+}
+const CALLS_USAGE = "nylorun tenant calls [--after <cursor>] [--limit <n>] [--tenant <name>]";
+/**
+ * `nylorun tenant calls`: every recorded model call from `--after`, one JSON object per line
+ * (NDJSON) on stdout, page by page (`--limit` a page) until caught up; then the cursor to resume
+ * from on stderr. Rows may repeat across runs: deduplicate by id.
+ */
+export async function callsCommand(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--tenant", "--after", "--limit"] }, CALLS_USAGE);
+    if (flags.rest.length)
+        throw usageError(`Usage: ${CALLS_USAGE}`);
+    const after = flags.values.get("--after");
+    const limitFlag = flags.values.get("--limit");
+    const limit = limitFlag === undefined ? undefined : Number(limitFlag);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 1 && limit <= 1000))
+        throw usageError("--limit is a whole number from 1 to 1000.");
+    const admin = await client(deps, flags.values.get("--tenant"));
+    let next = null;
+    for await (const page of admin.models.exportCalls({
+        ...(after === undefined ? {} : { after }),
+        ...(limit === undefined ? {} : { limit }),
+    })) {
+        for (const call of page.calls)
+            deps.out(JSON.stringify(call));
+        next = page.next;
+    }
+    if (next !== null)
+        deps.err(`Caught up. Resume with --after ${next}`);
+    return 0;
+}

package/dist/client/runtime.d.ts

@@ -0,0 +1,40 @@
+import { AgentsClient } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseStackFlags, type StackDeps } from "../stack/commands.js";
+import { type Connection } from "./target.js";
+/** Flags every Runtime API command takes. */
+export declare const RUNTIME_FLAGS: {
+    readonly values: readonly ["--tenant", "--as"];
+    readonly lists: readonly ["--scope"];
+};
+export declare const runtimeFlagsUsage: string;
+export declare const usageError: (message: string) => CliError;
+export type Flags = ReturnType<typeof parseStackFlags>;
+/** `args` parsed with the Runtime flags added to `allowed`. */
+export declare function parseFlags(args: readonly string[], allowed: {
+    booleans?: readonly string[];
+    values?: readonly string[];
+    lists?: readonly string[];
+}, usage: string): Flags;
+/** Exactly `count` positional arguments, else a usage error. */
+export declare function positional(flags: Flags, count: number, usage: string): string[];
+/** The Runtime API client of the installation the flags (or the environment) name. */
+export declare function runtimeClient(deps: StackDeps, flags: Flags): Promise<{
+    client: AgentsClient;
+    connection: Connection;
+}>;
+/** Runs `command`, turning a Runtime's refusal into a `CliError` with its message (exit 1). */
+export declare function runtimeCall<T>(command: () => Promise<T>): Promise<T>;
+/** Standard input, whole. */
+export declare function readStdin(): Promise<Buffer>;
+/** A JSON object from file `path`, or from standard input when `path` is `-`. */
+export declare function readJson(path: string, what: string): Promise<Record<string, unknown>>;
+/** A JSON value given on the command line. */
+export declare function parseJsonArgument(text: string, what: string): unknown;
+/** `key=value` pairs (`--label`), as a record. */
+export declare function labelsOf(flags: Flags, name?: string): Record<string, string> | undefined;
+/** A positive integer flag, when given. */
+export declare function integerFlag(flags: Flags, name: string): number | undefined;
+export { printJson, printTable } from "./io.js";
+/** A page's `next cursor` hint, when there is one. */
+export declare function printCursor(deps: StackDeps, cursor: string | null | undefined): void;