nylorun 0.14.0-beta → 0.15.1-beta

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

@@ -1,27 +1,27 @@
 /**
- * `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. `--environment <id>` sends that Environment's
+ * `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";
+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 mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]";
+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 (client.environments.secrets.put of @nylorun/agents, or Studio)";
+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): ${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 mcp inspect <url> --environment <id>.`;
+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;
@@ -36,8 +36,10 @@ async function inspect(deps, args) {
     const name = flags.values.get("--server");
     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}`,
@@ -56,7 +58,7 @@ async function inspect(deps, args) {
     });
     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})` : "";
@@ -143,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/configure.d.ts

@@ -46,7 +46,7 @@ export declare function configureProvider(options?: {
     root?: string;
     input?: Readable;
     output?: Writable;
-    /** Tenant API catalog from GET /v1/tenant/models. */
+    /** Management API catalog from GET /v1/tenant/models. */
     catalog?: ModelCatalog;
     /** This installation's stable id, for OAuth flows that need one (OpenAI). */
     deviceId?: () => string;

package/dist/client/model/configure.js

@@ -16,7 +16,7 @@ export class ConfigurationCancelled extends CliError {
 }
 /**
  * Build a pi-ai registry for interactive login. Catalog listing prefers the
- * Tenant API payload when provided (F2-4).
+ * Management API payload when provided (F2-4).
  */
 function modelsFor({ builtinModels, createProvider, stream, streamSimple }, selection, credentials, catalog) {
     const models = builtinModels({ credentials });

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;

package/dist/client/runtime.js

@@ -0,0 +1,134 @@
+/**
+ * What the Runtime API groups (`agents`, `sessions`, `environments`, `artifacts`) share: their
+ * flags, the `@nylorun/agents` client of the installation `target.ts` picks, acting for a subject
+ * with `--as`, and how they read input and print output.
+ */
+import { readFile } from "node:fs/promises";
+import { AgentsClient, RuntimeError, SUBJECT_SCOPES, } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { connect } from "./target.js";
+/** Flags every Runtime API command takes. */
+export const RUNTIME_FLAGS = { values: ["--tenant", "--as"], lists: ["--scope"] };
+export const runtimeFlagsUsage = `Every command takes --tenant <name>, and --as <subject> [--scope <scope>]... to act for a
+person (default scope sessions:own; scopes: ${SUBJECT_SCOPES.join(", ")}).`;
+export const usageError = (message) => new CliError(message, 2);
+/** `args` parsed with the Runtime flags added to `allowed`. */
+export function parseFlags(args, allowed, usage) {
+    return parseStackFlags(args, {
+        booleans: allowed.booleans ?? [],
+        values: [...RUNTIME_FLAGS.values, ...(allowed.values ?? [])],
+        lists: [...RUNTIME_FLAGS.lists, ...(allowed.lists ?? [])],
+    }, usage);
+}
+/** Exactly `count` positional arguments, else a usage error. */
+export function positional(flags, count, usage) {
+    if (flags.rest.length !== count)
+        throw usageError(`Usage: ${usage}`);
+    return flags.rest;
+}
+/** The Runtime API client of the installation the flags (or the environment) name. */
+export async function runtimeClient(deps, flags) {
+    const scopes = flags.lists.get("--scope");
+    const subject = flags.values.get("--as");
+    if (scopes && subject === undefined)
+        throw usageError("--scope needs --as <subject>.");
+    for (const scope of scopes ?? [])
+        if (!SUBJECT_SCOPES.includes(scope))
+            throw usageError(`Unknown scope ${scope}: one of ${SUBJECT_SCOPES.join(", ")}.`);
+    const connection = await connect(deps, "runtime", flags.values.get("--tenant"));
+    const fetch = (input, init) => deps.fetch(input instanceof Request ? input.url : String(input), init);
+    const token = connection.token;
+    if (!token && !connection.applicationKey)
+        throw new CliError(`No application key for ${connection.label}: set NYLORUN_SERVER_KEY.`, 1);
+    const base = new AgentsClient({
+        url: connection.url,
+        fetch,
+        ...(token
+            ? { token: { get: async () => token, invalidate: () => { } } }
+            : { key: connection.applicationKey }),
+    });
+    const client = subject === undefined
+        ? base
+        : base.as(subject, scopes ? { scopes: scopes } : {});
+    return { client, connection };
+}
+/** Runs `command`, turning a Runtime's refusal into a `CliError` with its message (exit 1). */
+export async function runtimeCall(command) {
+    try {
+        return await command();
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeError))
+            throw error;
+        const body = error.body;
+        const message = typeof body?.message === "string" ? body.message : error.message;
+        const code = typeof body?.code === "string" ? ` (${body.code})` : "";
+        throw new CliError(`${message.replace(/\.$/, "")}${code}. HTTP ${error.status}.`, 1);
+    }
+}
+/** Standard input, whole. */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+/** A JSON object from file `path`, or from standard input when `path` is `-`. */
+export async function readJson(path, what) {
+    let text;
+    try {
+        text = path === "-" ? (await readStdin()).toString("utf8") : await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new CliError(`Cannot read ${what.toLowerCase()} from ${path}: ${error.message}`, 1);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw usageError(`${what} is not JSON: ${error.message}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw usageError(`${what} must be a JSON object.`);
+    return value;
+}
+/** A JSON value given on the command line. */
+export function parseJsonArgument(text, what) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw usageError(`${what} is not JSON: ${error.message}`);
+    }
+}
+/** `key=value` pairs (`--label`), as a record. */
+export function labelsOf(flags, name = "--label") {
+    const pairs = flags.lists.get(name);
+    if (!pairs)
+        return undefined;
+    const labels = {};
+    for (const pair of pairs) {
+        const at = pair.indexOf("=");
+        if (at <= 0)
+            throw usageError(`${name} must be key=value, not ${pair}`);
+        labels[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    return labels;
+}
+/** A positive integer flag, when given. */
+export function integerFlag(flags, name) {
+    const raw = flags.values.get(name);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw usageError(`${name} must be a whole number, not ${raw}`);
+    return Number(raw);
+}
+export { printJson, printTable } from "./io.js";
+/** A page's `next cursor` hint, when there is one. */
+export function printCursor(deps, cursor) {
+    if (cursor)
+        deps.err(`More: --cursor ${cursor}`);
+}

package/dist/client/sessions.d.ts

@@ -0,0 +1,4 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const sessionsUsage: string;
+/** `nylorun sessions <command> ...` */
+export declare function sessionsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;