nylorun 0.13.0-beta → 0.15.0-beta

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>;

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;