nylorun 0.14.0-beta → 0.15.0-beta

package/dist/client/sessions.js

@@ -0,0 +1,295 @@
+/**
+ * `nylorun sessions`: the Tenant's sessions (`/v1/sessions`, Runtime API): open one, send it a
+ * message, answer what it waits for, watch its events, and read its history, usage, calls and
+ * traces. `exec` runs a command in the session's sandbox, as an app's own tool would.
+ */
+import { randomUUID } from "node:crypto";
+import { CliError } from "../errors.js";
+import { integerFlag, parseFlags, parseJsonArgument, positional, printCursor, printJson, printTable, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const sessionsUsage = `nylorun sessions <command>
+
+The Tenant's sessions, through the Runtime API with an application key (or NYLORUN_TOKEN).
+
+  list [--agent <id>] [--status <status>] [--environment <id>] [--owner <user>]
+       [--limit <n>] [--cursor <c>] [--json]
+  create --agent <id> --owner <user> [--environment <id>] [--id <id>] [--info <json>]
+                                      open a session; prints its id
+  get <id>                            the session: status, active turn, what it waits for
+  send <id> [<text>] [--data <json>] [--file <artifact>[@<version>]]... [--idempotency-key <k>]
+                                      start a turn with text, JSON data or files (artifacts)
+  approve <id> <interaction> [--deny] approve (or deny) a held tool call
+  respond <id> <interaction> <json>   answer a question the agent asked
+  cancel <id> [--reason <text>]       cancel the running turn
+  watch <id> [--follow] [--cursor <c>]
+                                      the session's events as JSON lines until interrupted;
+                                      --follow adds the sessions of agents it uses as tools
+  history <id> [--agent <a>] [--limit <n>] [--cursor <c>]
+  usage <id> [--turn <id>]            tokens and cost
+  calls <id> [--tool] [--turn <id>] [--limit <n>] [--cursor <c>]
+                                      model calls (--tool: tool calls)
+  trace <id> <turn>                   the turn's spans as OTLP JSON
+  exec <id> [--timeout <s>] -- <command>...
+                                      run a command in the session's sandbox (bash); exits with
+                                      its exit code
+
+${runtimeFlagsUsage}`;
+async function list(deps, args) {
+    const usage = "nylorun sessions list [--agent <id>] [--status <s>] [--environment <id>] [--owner <user>] [--limit <n>] [--cursor <c>] [--json]";
+    const flags = parseFlags(args, { booleans: ["--json"], values: ["--agent", "--status", "--environment", "--owner", "--limit", "--cursor"] }, usage);
+    positional(flags, 0, usage);
+    const { client } = await runtimeClient(deps, flags);
+    const value = (name) => flags.values.get(name);
+    const limit = integerFlag(flags, "--limit");
+    const page = await runtimeCall(() => client.sessions.page({
+        ...(value("--agent") ? { agentId: value("--agent") } : {}),
+        ...(value("--status") ? { status: value("--status") } : {}),
+        ...(value("--environment") ? { environmentId: value("--environment") } : {}),
+        ...(value("--owner") ? { ownerUserId: value("--owner") } : {}),
+        ...(limit === undefined ? {} : { limit }),
+        ...(value("--cursor") ? { cursor: value("--cursor") } : {}),
+    }));
+    if (flags.booleans.has("--json")) {
+        printJson(deps, page);
+        return 0;
+    }
+    if (page.sessions.length === 0)
+        deps.out("No sessions.");
+    else
+        printTable(deps, [
+            ["ID", "AGENT", "OWNER", "STATUS", "ENVIRONMENT", "LAST EVENT"],
+            ...page.sessions.map((session) => [
+                session.id,
+                session.agentId,
+                session.ownerUserId,
+                session.status,
+                session.environmentId ?? "-",
+                session.lastEventAt ?? "-",
+            ]),
+        ]);
+    printCursor(deps, page.nextCursor);
+    return 0;
+}
+async function create(deps, args) {
+    const usage = "nylorun sessions create --agent <id> --owner <user> [--environment <id>] [--id <id>] [--info <json>]";
+    const flags = parseFlags(args, { values: ["--agent", "--owner", "--environment", "--id", "--info"] }, usage);
+    positional(flags, 0, usage);
+    const agentId = flags.values.get("--agent");
+    const ownerUserId = flags.values.get("--owner");
+    if (!agentId || !ownerUserId)
+        throw usageError(`Usage: ${usage}`);
+    const info = flags.values.get("--info");
+    const parsedInfo = info === undefined ? undefined : parseJsonArgument(info, "--info");
+    if (parsedInfo !== undefined && (!parsedInfo || typeof parsedInfo !== "object" || Array.isArray(parsedInfo)))
+        throw usageError("--info must be a JSON object.");
+    const environment = flags.values.get("--environment");
+    const id = flags.values.get("--id");
+    const { client } = await runtimeClient(deps, flags);
+    const session = await runtimeCall(() => client.createSession({
+        agentId,
+        ownerUserId,
+        ...(id ? { id } : {}),
+        ...(environment ? { environment } : {}),
+        ...(parsedInfo ? { info: parsedInfo } : {}),
+    }));
+    deps.out(session.id);
+    return 0;
+}
+async function get(deps, args) {
+    const usage = "nylorun sessions get <id>";
+    const flags = parseFlags(args, {}, usage);
+    const [id] = positional(flags, 1, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).inspect()));
+    return 0;
+}
+/** `artifact` or `artifact@version`, as a file part. */
+function filePart(value) {
+    const at = value.lastIndexOf("@");
+    if (at <= 0)
+        return { type: "file", artifactId: value };
+    const version = value.slice(at + 1);
+    if (!/^[1-9]\d*$/.test(version))
+        throw usageError(`--file ${value}: the version must be a positive number.`);
+    return { type: "file", artifactId: value.slice(0, at), version: Number(version) };
+}
+async function send(deps, args) {
+    const usage = "nylorun sessions send <id> [<text>] [--data <json>] [--file <artifact>[@<version>]]... [--idempotency-key <k>]";
+    const flags = parseFlags(args, { values: ["--data", "--idempotency-key"], lists: ["--file"] }, usage);
+    if (flags.rest.length < 1 || flags.rest.length > 2)
+        throw usageError(`Usage: ${usage}`);
+    const [id, text] = flags.rest;
+    const data = flags.values.get("--data");
+    const files = flags.lists.get("--file") ?? [];
+    if (data !== undefined && (text !== undefined || files.length))
+        throw usageError("--data is a message of its own: pass it without text or --file.");
+    if (data === undefined && text === undefined && files.length === 0)
+        throw usageError(`Nothing to send. Usage: ${usage}`);
+    const parts = files.map(filePart);
+    const options = { idempotencyKey: flags.values.get("--idempotency-key") ?? randomUUID() };
+    const { client } = await runtimeClient(deps, flags);
+    const session = client.session(id);
+    const accepted = await runtimeCall(() => data !== undefined
+        ? session.input(parseJsonArgument(data, "--data"), options)
+        : parts.length
+            ? session.inputParts([...(text ? [{ type: "text", text }] : []), ...parts], options)
+            : session.input(text, options));
+    printJson(deps, accepted);
+    return 0;
+}
+async function approve(deps, args) {
+    const usage = "nylorun sessions approve <id> <interaction> [--deny]";
+    const flags = parseFlags(args, { booleans: ["--deny"] }, usage);
+    const [id, interaction] = positional(flags, 2, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).approve(interaction, !flags.booleans.has("--deny"), { idempotencyKey: randomUUID() })));
+    return 0;
+}
+async function respond(deps, args) {
+    const usage = "nylorun sessions respond <id> <interaction> <json>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, interaction, value] = positional(flags, 3, usage);
+    const answer = parseJsonArgument(value, "The answer");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).respond(interaction, answer, { idempotencyKey: randomUUID() })));
+    return 0;
+}
+async function cancel(deps, args) {
+    const usage = "nylorun sessions cancel <id> [--reason <text>]";
+    const flags = parseFlags(args, { values: ["--reason"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const reason = flags.values.get("--reason");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).cancel({ idempotencyKey: randomUUID(), ...(reason ? { reason } : {}) })));
+    return 0;
+}
+async function watch(deps, args) {
+    const usage = "nylorun sessions watch <id> [--follow] [--cursor <c>]";
+    const flags = parseFlags(args, { booleans: ["--follow"], values: ["--cursor"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const cursor = flags.values.get("--cursor");
+    const { client } = await runtimeClient(deps, flags);
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        await runtimeCall(async () => {
+            for await (const event of client.session(id).observe({
+                follow: flags.booleans.has("--follow"),
+                signal: controller.signal,
+                ...(cursor ? { cursor } : {}),
+            }))
+                deps.out(JSON.stringify(event));
+        });
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            throw error;
+    }
+    finally {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+    }
+    return 0;
+}
+async function history(deps, args) {
+    const usage = "nylorun sessions history <id> [--agent <a>] [--limit <n>] [--cursor <c>]";
+    const flags = parseFlags(args, { values: ["--agent", "--limit", "--cursor"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const limit = integerFlag(flags, "--limit");
+    const agent = flags.values.get("--agent");
+    const cursor = flags.values.get("--cursor");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).history({
+        ...(agent ? { agent } : {}),
+        ...(cursor ? { cursor } : {}),
+        ...(limit === undefined ? {} : { limit }),
+    })));
+    return 0;
+}
+async function usageOf(deps, args) {
+    const usage = "nylorun sessions usage <id> [--turn <id>]";
+    const flags = parseFlags(args, { values: ["--turn"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const turnId = flags.values.get("--turn");
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).usage(turnId ? { turnId } : {})));
+    return 0;
+}
+async function calls(deps, args) {
+    const usage = "nylorun sessions calls <id> [--tool] [--turn <id>] [--limit <n>] [--cursor <c>]";
+    const flags = parseFlags(args, { booleans: ["--tool"], values: ["--turn", "--limit", "--cursor"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const turnId = flags.values.get("--turn");
+    const cursor = flags.values.get("--cursor");
+    const limit = integerFlag(flags, "--limit");
+    const options = {
+        ...(turnId ? { turnId } : {}),
+        ...(cursor ? { cursor } : {}),
+        ...(limit === undefined ? {} : { limit }),
+    };
+    const { client } = await runtimeClient(deps, flags);
+    const session = client.session(id);
+    const page = flags.booleans.has("--tool")
+        ? await runtimeCall(() => session.toolCalls(options))
+        : await runtimeCall(() => session.modelCalls(options));
+    printJson(deps, page);
+    return 0;
+}
+async function trace(deps, args) {
+    const usage = "nylorun sessions trace <id> <turn>";
+    const flags = parseFlags(args, {}, usage);
+    const [id, turn] = positional(flags, 2, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.session(id).trace(turn)));
+    return 0;
+}
+async function exec(deps, args) {
+    const usage = "nylorun sessions exec <id> [--timeout <s>] -- <command>...";
+    const split = args.indexOf("--");
+    if (split < 0 || split === args.length - 1)
+        throw usageError(`Usage: ${usage}`);
+    const flags = parseFlags(args.slice(0, split), { values: ["--timeout"] }, usage);
+    const [id] = positional(flags, 1, usage);
+    const timeout = integerFlag(flags, "--timeout");
+    const command = args.slice(split + 1).join(" ");
+    const { client } = await runtimeClient(deps, flags);
+    // The Runtime answers the tool's outcome: `completed` with its output, or why it did not run.
+    const outcome = (await runtimeCall(() => client.session(id).sandbox.bash({ command, ...(timeout === undefined ? {} : { timeout }) })));
+    if (outcome.kind !== "completed")
+        throw new CliError(`The command did not run (${outcome.kind ?? "no outcome"}): ${outcome.error?.message ?? JSON.stringify(outcome)}`, 1);
+    const result = outcome.output;
+    if (result.stdout)
+        deps.out(result.stdout.replace(/\n$/, ""));
+    if (result.stderr)
+        deps.err(result.stderr.replace(/\n$/, ""));
+    return typeof result.exitCode === "number" ? result.exitCode : 0;
+}
+const COMMANDS = {
+    list,
+    ls: list,
+    create,
+    get,
+    send,
+    approve,
+    respond,
+    cancel,
+    watch,
+    history,
+    usage: usageOf,
+    calls,
+    trace,
+    exec,
+};
+/** `nylorun sessions <command> ...` */
+export async function sessionsCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "-h") {
+        deps.out(sessionsUsage);
+        return 0;
+    }
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(sub ? `Unknown sessions command ${sub}.\n${sessionsUsage}` : sessionsUsage);
+    return command(deps, rest);
+}

package/dist/client/settings.d.ts

@@ -0,0 +1,12 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const settingsUsage = "  budgets [get | put <file|->] [--tenant <name>]\n                                      the model spend caps; put replaces them all\n  tool-policy [get | put <file|->] [--tenant <name>]\n                                      the Tool Gate's rules; put replaces them all\n  settings sandbox [get | put <file|->] [--tenant <name>]\n                                      the Environment settings: limits, stop grace, placement\n  settings artifacts [get | put <file|->] [--tenant <name>]\n                                      the artifact store's limits\n  coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]\n                                      which secret of the Environment each of the agent's MCP\n                                      servers and HTTP tools would get";
+export declare const budgetsCommand: (deps: StackDeps, args: readonly string[]) => Promise<number>;
+export declare const toolPolicyCommand: (deps: StackDeps, args: readonly string[]) => Promise<number>;
+/** `nylorun tenant settings sandbox | artifacts ...` */
+export declare function settingsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;
+/**
+ * `nylorun tenant coverage`: which secret of `--environment` each remote MCP server and HTTP tool
+ * of saved agent `--agent` would get in a session (none without an Environment). It reads no
+ * secret and calls no server.
+ */
+export declare function coverageCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/settings.js

@@ -0,0 +1,103 @@
+import { PutModelBudgetsRequestSchema, PutTenantArtifactsRequestSchema, PutTenantEnvironmentsRequestSchema, PutToolPolicyRequestSchema, } from "@nylorun/core/contracts";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { printJson, printTable, readBody } from "./io.js";
+import { connect, managementClient } from "./target.js";
+export const settingsUsage = `  budgets [get | put <file|->] [--tenant <name>]
+                                      the model spend caps; put replaces them all
+  tool-policy [get | put <file|->] [--tenant <name>]
+                                      the Tool Gate's rules; put replaces them all
+  settings sandbox [get | put <file|->] [--tenant <name>]
+                                      the Environment settings: limits, stop grace, placement
+  settings artifacts [get | put <file|->] [--tenant <name>]
+                                      the artifact store's limits
+  coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]
+                                      which secret of the Environment each of the agent's MCP
+                                      servers and HTTP tools would get`;
+const usageError = (message = `Usage:\n${settingsUsage}`) => new CliError(message, 2);
+/* The bodies' `requestId` is optional in the contracts; the client adds one when it is absent. */
+const budgets = {
+    name: "budgets",
+    schema: PutModelBudgetsRequestSchema,
+    get: (admin) => admin.models.budgets.get(),
+    put: (admin, body) => admin.models.budgets.put(body),
+};
+const toolPolicy = {
+    name: "tool-policy",
+    schema: PutToolPolicyRequestSchema,
+    readOnly: ["updatedAt"],
+    get: (admin) => admin.toolPolicy.get(),
+    put: (admin, body) => admin.toolPolicy.put(body),
+};
+const sandbox = {
+    name: "settings sandbox",
+    schema: PutTenantEnvironmentsRequestSchema,
+    get: (admin) => admin.settings.sandbox.get(),
+    put: (admin, body) => admin.settings.sandbox.put(body),
+};
+const artifacts = {
+    name: "settings artifacts",
+    schema: PutTenantArtifactsRequestSchema,
+    readOnly: ["usedBytes"],
+    get: (admin) => admin.settings.artifacts.get(),
+    put: (admin, body) => admin.settings.artifacts.put(body),
+};
+/** `<document> [get | put <file|->]`: `get` when no verb is given. */
+async function documentCommand(deps, document, args) {
+    const usage = `nylorun tenant ${document.name} [get | put <file|->] [--tenant <name>]`;
+    const flags = parseStackFlags(args, { values: ["--tenant"] }, usage);
+    const [verb = "get", ...operands] = flags.rest;
+    if (!((verb === "get" && !operands.length) || (verb === "put" && operands.length === 1)))
+        throw usageError(`Usage: ${usage}`);
+    const body = verb === "put" ? await readBody(deps, operands[0], document.schema, document.readOnly) : undefined;
+    const admin = managementClient(deps, await connect(deps, "management", flags.values.get("--tenant")));
+    printJson(deps, body === undefined ? await document.get(admin) : await document.put(admin, body));
+    return 0;
+}
+export const budgetsCommand = (deps, args) => documentCommand(deps, budgets, args);
+export const toolPolicyCommand = (deps, args) => documentCommand(deps, toolPolicy, args);
+/** `nylorun tenant settings sandbox | artifacts ...` */
+export async function settingsCommand(deps, args) {
+    const [which, ...rest] = args;
+    if (which === "sandbox")
+        return documentCommand(deps, sandbox, rest);
+    if (which === "artifacts")
+        return documentCommand(deps, artifacts, rest);
+    throw usageError();
+}
+const COVERAGE_USAGE = "nylorun tenant coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]";
+/**
+ * `nylorun tenant coverage`: which secret of `--environment` each remote MCP server and HTTP tool
+ * of saved agent `--agent` would get in a session (none without an Environment). It reads no
+ * secret and calls no server.
+ */
+export async function coverageCommand(deps, args) {
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant", "--agent", "--environment"] }, COVERAGE_USAGE);
+    const agentId = flags.values.get("--agent");
+    const environmentId = flags.values.get("--environment");
+    if (flags.rest.length || agentId === undefined)
+        throw usageError(`Usage: ${COVERAGE_USAGE}`);
+    const admin = managementClient(deps, await connect(deps, "management", flags.values.get("--tenant")));
+    const coverage = await admin.coverage({
+        agentId,
+        ...(environmentId === undefined ? {} : { environmentId }),
+    });
+    if (flags.booleans.has("--json")) {
+        printJson(deps, coverage);
+        return 0;
+    }
+    const missing = coverage.entries.filter((entry) => entry.status === "missing").length;
+    deps.out(`${coverage.agentId} in ${coverage.environmentId ?? "no Environment"}: ${coverage.complete ? "every credential is covered" : `${missing} of ${coverage.entries.length} missing`}`);
+    if (coverage.entries.length)
+        printTable(deps, [
+            ["STATUS", "KIND", "NAME", "URL", "SECRET"],
+            ...coverage.entries.map((entry) => [
+                entry.status,
+                entry.kind,
+                entry.agentId ? `${entry.agentId}/${entry.name}` : entry.name,
+                entry.url,
+                entry.credential?.name ?? (entry.required ? "(required)" : ""),
+            ]),
+        ]);
+    return 0;
+}

package/dist/client/signing-keys.d.ts

@@ -0,0 +1,3 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const signingKeysUsage = "  signing-keys list [--tenant <name>]\n                                      the Tenant's token signing keys\n  signing-keys rotate [--force] [--tenant <name>]\n                                      rotate; --force ends outstanding links and run tokens\n  signing-keys revoke <kid> [--tenant <name>]\n                                      revoke a previous or standby key";
+export declare function signingKeysCommand(deps: StackDeps, input: readonly string[]): Promise<number>;

package/dist/client/signing-keys.js

@@ -0,0 +1,32 @@
+/**
+ * `nylorun tenant signing-keys`: the Tenant's signing keys, which sign capability links and run
+ * tokens, through the Management API. (Subject tokens, the access policy, browser keys and
+ * revocations left the Runtime in protocol 7.)
+ */
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { connect, managementClient } from "./target.js";
+export const signingKeysUsage = `  signing-keys list [--tenant <name>]
+                                      the Tenant's token signing keys
+  signing-keys rotate [--force] [--tenant <name>]
+                                      rotate; --force ends outstanding links and run tokens
+  signing-keys revoke <kid> [--tenant <name>]
+                                      revoke a previous or standby key`;
+const usageError = (message = `Usage:\n${signingKeysUsage}`) => new CliError(message, 2);
+export async function signingKeysCommand(deps, input) {
+    const [action, ...args] = input;
+    const flags = parseStackFlags(args, { booleans: action === "rotate" ? ["--force"] : [], values: ["--tenant"] }, signingKeysUsage);
+    const arity = action === "revoke" ? 1 : 0;
+    if (!["list", "rotate", "revoke"].includes(action ?? "") || flags.rest.length !== arity)
+        throw usageError();
+    const keys = managementClient(deps, await connect(deps, "management", flags.values.get("--tenant")))
+        .signingKeys;
+    const print = (value) => deps.out(JSON.stringify(value, null, 2));
+    if (action === "list")
+        print(await keys.list());
+    else if (action === "rotate")
+        print(await keys.rotate({ force: flags.booleans.has("--force") }));
+    else
+        print(await keys.revoke(flags.rest[0]));
+    return 0;
+}

package/dist/client/target.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The installation a client command acts on. `--tenant <name>` names a local Tenant. Without it,
+ * `NYLORUN_RUNTIME_URL` with the key the API needs names a remote installation:
+ * `NYLORUN_MANAGEMENT_KEY` for the Management API (`nylorun tenant`), `NYLORUN_SERVER_KEY` or an
+ * identity provider's token in `NYLORUN_TOKEN` for the Runtime API (`NYLORUN_RUNTIME_URL` alone is
+ * an app's, as for `createAdmin`). Otherwise the local
+ * Tenant the Project link names, else the default one, while it runs (`runningTenantApi`: the
+ * Project's keys while they authenticate, else the Host root's own).
+ */
+import { type ManagementClient } from "@nylorun/admin";
+import { type StackDeps } from "../stack/commands.js";
+export type Api = "management" | "runtime";
+export interface Connection {
+    /** How messages name it: `Tenant <name>`, or the remote URL. */
+    label: string;
+    url: string;
+    /** A local Tenant (Docker on this machine), else a remote installation. */
+    local: boolean;
+    /** The local Tenant's name. */
+    tenant?: string;
+    applicationKey?: string;
+    managementKey?: string;
+    /** A trusted issuer's token (`NYLORUN_TOKEN`), sent in place of the application key. */
+    token?: string;
+}
+/** The remote installation the environment names for `api`, if it names one. */
+export declare function remoteConnection(env: StackDeps["env"], api: Api): Connection | undefined;
+/** The installation to act on for `api` (module comment). */
+export declare function connect(deps: StackDeps, api: Api, tenant?: string): Promise<Connection>;
+/** The Management API client of `connection`, through `deps.fetch`. */
+export declare function managementClient(deps: StackDeps, connection: Connection): ManagementClient;
+/** `error`'s message, ending in one full stop. */
+export declare function messageOf(error: unknown): string;

package/dist/client/target.js

@@ -0,0 +1,65 @@
+/**
+ * The installation a client command acts on. `--tenant <name>` names a local Tenant. Without it,
+ * `NYLORUN_RUNTIME_URL` with the key the API needs names a remote installation:
+ * `NYLORUN_MANAGEMENT_KEY` for the Management API (`nylorun tenant`), `NYLORUN_SERVER_KEY` or an
+ * identity provider's token in `NYLORUN_TOKEN` for the Runtime API (`NYLORUN_RUNTIME_URL` alone is
+ * an app's, as for `createAdmin`). Otherwise the local
+ * Tenant the Project link names, else the default one, while it runs (`runningTenantApi`: the
+ * Project's keys while they authenticate, else the Host root's own).
+ */
+import { createManagementClient } from "@nylorun/admin";
+import { CliError } from "../errors.js";
+import { runningTenantApi } from "../stack/commands.js";
+function variable(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+/** The remote installation the environment names for `api`, if it names one. */
+export function remoteConnection(env, api) {
+    const url = variable(env, "NYLORUN_RUNTIME_URL");
+    const managementKey = variable(env, "NYLORUN_MANAGEMENT_KEY");
+    const applicationKey = variable(env, "NYLORUN_SERVER_KEY");
+    const token = variable(env, "NYLORUN_TOKEN");
+    if (!url || (api === "management" ? !managementKey : !applicationKey && !token))
+        return undefined;
+    return {
+        label: url,
+        url: url.replace(/\/$/, ""),
+        local: false,
+        ...(applicationKey ? { applicationKey } : {}),
+        ...(managementKey ? { managementKey } : {}),
+        // A token is a person's: it wins over the key for the Runtime API.
+        ...(token && api === "runtime" ? { token } : {}),
+    };
+}
+/** The installation to act on for `api` (module comment). */
+export async function connect(deps, api, tenant) {
+    if (tenant === undefined) {
+        const remote = remoteConnection(deps.env, api);
+        if (remote)
+            return remote;
+    }
+    const local = await runningTenantApi(deps, tenant === undefined ? {} : { name: tenant });
+    return {
+        label: `Tenant ${local.name}`,
+        url: local.runtimeUrl,
+        local: true,
+        tenant: local.name,
+        applicationKey: local.applicationKey,
+        managementKey: local.managementKey,
+    };
+}
+/** The Management API client of `connection`, through `deps.fetch`. */
+export function managementClient(deps, connection) {
+    if (!connection.managementKey)
+        throw new CliError(`No management key for ${connection.label}: set NYLORUN_MANAGEMENT_KEY, or on the Runtime's machine run "nylorun tenant keys put <id> --management".`, 1);
+    return createManagementClient({
+        url: connection.url,
+        key: connection.managementKey,
+        fetch: (input, init) => deps.fetch(input instanceof Request ? input.url : String(input), init),
+    });
+}
+/** `error`'s message, ending in one full stop. */
+export function messageOf(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\.?$/, ".");
+}

package/dist/client/tenant.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `nylorun tenant`: the Management API (`/v1/tenant/*`) of the installation's one Tenant, with a
+ * management key (`target.ts` picks the installation). Issuing a management key is the one
+ * exception: only the Runtime's machine does it, through `nylorun-operate` (`stack/keys.ts`).
+ */
+import type { ManagementClient } from "@nylorun/admin";
+import { type StackDeps } from "../stack/commands.js";
+import { type Connection } from "./target.js";
+export declare const tenantUsage = "nylorun tenant <command>\n\nThe Management API of the installation's one Tenant, with a management key: the local Tenant\n--tenant names (else the linked project's, else the default one), or the installation that\nNYLORUN_RUNTIME_URL and NYLORUN_MANAGEMENT_KEY name.\n\n  reset [--sessions|--environments|--all] [--yes] [--tenant <name>]\n                                      clear the Tenant's sessions, Environments or all its data\n                                      (the Project link and keys stay)\n  keys put <id> [--management] [--tenant <name>]\n                                      create the Tenant's application key <id> (--management: a\n                                      management key, on the Runtime's machine only), or rotate it\n                                      (the old key stops working); prints the key once\n  keys list [--tenant <name>] [--json]\n                                      the Tenant's keys: id, role, when issued (never the keys)\n  keys rm <id> [--tenant <name>]      delete key <id>: it stops working at once\n  signing-keys list [--tenant <name>]\n                                      the Tenant's token signing keys\n  signing-keys rotate [--force] [--tenant <name>]\n                                      rotate; --force ends outstanding links and run tokens\n  signing-keys revoke <kid> [--tenant <name>]\n                                      revoke a previous or standby key\n  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)\n  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\n  budgets [get | put <file|->] [--tenant <name>]\n                                      the model spend caps; put replaces them all\n  tool-policy [get | put <file|->] [--tenant <name>]\n                                      the Tool Gate's rules; put replaces them all\n  settings sandbox [get | put <file|->] [--tenant <name>]\n                                      the Environment settings: limits, stop grace, placement\n  settings artifacts [get | put <file|->] [--tenant <name>]\n                                      the artifact store's limits\n  coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]\n                                      which secret of the Environment each of the agent's MCP\n                                      servers and HTTP tools would get\n  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)\n\nA put reads a JSON body from a file, or from stdin for -, and replaces the whole document; what\nbudgets, tool-policy and settings artifacts get print, put takes back. An API key is read from\nstdin, never from the arguments.";
+/** The Management API client of the installation `--tenant` (or the environment) names. */
+export declare function tenantClient(deps: StackDeps, tenant: string | undefined): Promise<{
+    connection: Connection;
+    admin: ManagementClient;
+}>;
+/**
+ * `nylorun status` for an installation the environment names (`NYLORUN_RUNTIME_URL` and
+ * `NYLORUN_MANAGEMENT_KEY`): the Tenant, its checks and counts. A local Tenant's status is the
+ * stack's (`stack/commands.ts`).
+ */
+export declare function remoteStatus(deps: StackDeps, args: readonly string[]): Promise<number>;
+/** `nylorun tenant <group> ...` */
+export declare function tenantCommand(deps: StackDeps, args: readonly string[]): Promise<number>;