nylorun 0.16.0-beta → 0.18.0-beta

package/dist/client/sessions.js

@@ -1,5 +1,6 @@
 /**
- * `nylorun sessions`: the Tenant's sessions (`/v1/sessions`, Runtime API): open one, send it a
+ * `nylorun sessions`: the Tenant's sessions (`/v1/sessions`, Runtime API): open one on an Agent
+ * (protocol 16: every session runs on one, and its id is the caller's to choose), 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.
  */
@@ -10,13 +11,17 @@ 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>]
+  list [--agent <id>] [--manifest <name>] [--status <status>] [--owner <user>]
        [--limit <n>] [--cursor <c>] [--json]
-  create --agent <id> --owner <user> [--environment <id>] [--id <id>] [--info <json>]
-                                      open a session; prints its id
+                                      --agent: on that Agent; --manifest: on the Agents made
+                                      from that agent manifest
+  create --agent <id> --owner <user> [--id <id>] [--info <json>]
+                                      open a session on Agent <id>; 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)
+       [--reject-if-busy]             start a turn with text, JSON data or files (artifacts); while
+                                      a turn runs the message waits in the session's queue, or is
+                                      refused with --reject-if-busy
   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
@@ -33,9 +38,13 @@ The Tenant's sessions, through the Runtime API with an application key (or NYLOR
                                       its exit code
 
 ${runtimeFlagsUsage}`;
+/** Protocol 16: a session runs on the Agent `--agent` names, which holds what an Environment did. */
+const ENVIRONMENT_REMOVED = "--environment was removed in protocol 16: a session runs on an Agent, its sandbox and vault included. Pass --agent <id> (nylorun agents list).";
 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);
+    const usage = "nylorun sessions list [--agent <id>] [--manifest <name>] [--status <s>] [--owner <user>] [--limit <n>] [--cursor <c>] [--json]";
+    if (args.includes("--environment"))
+        throw usageError(ENVIRONMENT_REMOVED);
+    const flags = parseFlags(args, { booleans: ["--json"], values: ["--agent", "--manifest", "--status", "--owner", "--limit", "--cursor"] }, usage);
     positional(flags, 0, usage);
     const { client } = await runtimeClient(deps, flags);
     const value = (name) => flags.values.get(name);
@@ -43,7 +52,7 @@ async function list(deps, args) {
     const page = await runtimeCall(() => client.sessions.page({
         ...(value("--agent") ? { agentId: value("--agent") } : {}),
         ...(value("--status") ? { status: value("--status") } : {}),
-        ...(value("--environment") ? { environmentId: value("--environment") } : {}),
+        ...(value("--manifest") ? { manifest: value("--manifest") } : {}),
         ...(value("--owner") ? { ownerUserId: value("--owner") } : {}),
         ...(limit === undefined ? {} : { limit }),
         ...(value("--cursor") ? { cursor: value("--cursor") } : {}),
@@ -56,13 +65,12 @@ async function list(deps, args) {
         deps.out("No sessions.");
     else
         printTable(deps, [
-            ["ID", "AGENT", "OWNER", "STATUS", "ENVIRONMENT", "LAST EVENT"],
+            ["ID", "AGENT", "OWNER", "STATUS", "LAST EVENT"],
             ...page.sessions.map((session) => [
                 session.id,
                 session.agentId,
                 session.ownerUserId,
                 session.status,
-                session.environmentId ?? "-",
                 session.lastEventAt ?? "-",
             ]),
         ]);
@@ -70,8 +78,10 @@ async function list(deps, args) {
     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);
+    const usage = "nylorun sessions create --agent <id> --owner <user> [--id <id>] [--info <json>]";
+    if (args.includes("--environment"))
+        throw usageError(ENVIRONMENT_REMOVED);
+    const flags = parseFlags(args, { values: ["--agent", "--owner", "--id", "--info"] }, usage);
     positional(flags, 0, usage);
     const agentId = flags.values.get("--agent");
     const ownerUserId = flags.values.get("--owner");
@@ -81,14 +91,12 @@ async function create(deps, args) {
     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,
+        agent: agentId,
         ownerUserId,
         ...(id ? { id } : {}),
-        ...(environment ? { environment } : {}),
         ...(parsedInfo ? { info: parsedInfo } : {}),
     }));
     deps.out(session.id);
@@ -113,8 +121,8 @@ function filePart(value) {
     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);
+    const usage = "nylorun sessions send <id> [<text>] [--data <json>] [--file <artifact>[@<version>]]... [--idempotency-key <k>] [--reject-if-busy]";
+    const flags = parseFlags(args, { values: ["--data", "--idempotency-key"], lists: ["--file"], booleans: ["--reject-if-busy"] }, usage);
     if (flags.rest.length < 1 || flags.rest.length > 2)
         throw usageError(`Usage: ${usage}`);
     const [id, text] = flags.rest;
@@ -125,7 +133,10 @@ async function send(deps, args) {
     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 options = {
+        idempotencyKey: flags.values.get("--idempotency-key") ?? randomUUID(),
+        ...(flags.booleans.has("--reject-if-busy") ? { delivery: "reject" } : {}),
+    };
     const { client } = await runtimeClient(deps, flags);
     const session = client.session(id);
     const accepted = await runtimeCall(() => data !== undefined
@@ -247,9 +258,9 @@ async function trace(deps, args) {
 async function exec(deps, args) {
     const usage = "nylorun sessions exec <id> [--timeout <s>] -- <command>...";
     const split = args.indexOf("--");
+    const flags = parseFlags(split < 0 ? args : args.slice(0, split), { values: ["--timeout"] }, usage);
     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(" ");

package/dist/client/settings.d.ts

@@ -1,12 +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  settings skills [get | put <file|->] [--tenant <name>]\n                                      the most bytes one skill may hold\n  settings limits [get | put <file|->] [--tenant <name>]\n                                      the Runtime limits: sizes, counts and deadlines (record\n                                      entries, request bodies, Environments, model calls, tools)\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 settingsUsage = "  budgets [get | put <file|->] [--tenant <name>]\n                                      the model spend caps (scope tenant, manifest with id an\n                                      agent manifest's name, or turn); 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 Agents' environments: limits, stop grace, placement\n  settings artifacts [get | put <file|->] [--tenant <name>]\n                                      the artifact store's limits\n  settings skills [get | put <file|->] [--tenant <name>]\n                                      the most bytes one skill may hold\n  settings limits [get | put <file|->] [--tenant <name>]\n                                      the Runtime limits: sizes, counts and deadlines (record\n                                      entries, request bodies, Agents, model calls, tools)\n  coverage --agent <id> [--tenant <name>] [--json]\n                                      which secret of Agent <id>'s vault each MCP server and\n                                      HTTP tool of its manifest 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 | skills | limits ...` */
 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.
+ * `nylorun tenant coverage`: which secret of Agent `--agent`'s vault each remote MCP server and
+ * HTTP tool of the manifest version it runs would get in its sessions. It reads no secret and
+ * calls no server.
  */
 export declare function coverageCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/settings.js

@@ -1,24 +1,25 @@
 import { PutModelBudgetsRequestSchema, PutTenantArtifactsRequestSchema, PutTenantEnvironmentsRequestSchema, PutTenantLimitsRequestSchema, PutTenantSkillsRequestSchema, PutToolPolicyRequestSchema, } from "@nylorun/core/contracts";
-import { CliError } from "../errors.js";
-import { parseStackFlags } from "../stack/commands.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
+import { parseStackFlags, usageLinesOf } 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
+                                      the model spend caps (scope tenant, manifest with id an
+                                      agent manifest's name, or turn); 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
+                                      the Agents' environments: limits, stop grace, placement
   settings artifacts [get | put <file|->] [--tenant <name>]
                                       the artifact store's limits
   settings skills [get | put <file|->] [--tenant <name>]
                                       the most bytes one skill may hold
   settings limits [get | put <file|->] [--tenant <name>]
                                       the Runtime limits: sizes, counts and deadlines (record
-                                      entries, request bodies, Environments, model calls, tools)
-  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`;
+                                      entries, request bodies, Agents, model calls, tools)
+  coverage --agent <id> [--tenant <name>] [--json]
+                                      which secret of Agent <id>'s vault each MCP server and
+                                      HTTP tool of its manifest 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 = {
@@ -76,6 +77,8 @@ export const toolPolicyCommand = (deps, args) => documentCommand(deps, toolPolic
 /** `nylorun tenant settings sandbox | artifacts | skills | limits ...` */
 export async function settingsCommand(deps, args) {
     const [which, ...rest] = args;
+    if (isHelp(which))
+        throw new HelpRequest(usageLinesOf(settingsUsage, "settings"));
     if (which === "sandbox")
         return documentCommand(deps, sandbox, rest);
     if (which === "artifacts")
@@ -84,31 +87,29 @@ export async function settingsCommand(deps, args) {
         return documentCommand(deps, skillSettings, rest);
     if (which === "limits")
         return documentCommand(deps, limitSettings, rest);
-    throw usageError();
+    throw usageError(usageLinesOf(settingsUsage, "settings"));
 }
-const COVERAGE_USAGE = "nylorun tenant coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]";
+const COVERAGE_USAGE = "nylorun tenant coverage --agent <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.
+ * `nylorun tenant coverage`: which secret of Agent `--agent`'s vault each remote MCP server and
+ * HTTP tool of the manifest version it runs would get in its sessions. 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);
+    if (args.includes("--environment"))
+        throw usageError("--environment was removed in protocol 16: pass the Agent, --agent <id>, whose vault its sessions use.");
+    const flags = parseStackFlags(args, { booleans: ["--json"], values: ["--tenant", "--agent"] }, 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 }),
-    });
+    const coverage = await admin.coverage({ agentId });
     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`}`);
+    deps.out(`Agent ${coverage.agentId}: ${coverage.complete ? "every credential is covered" : `${missing} of ${coverage.entries.length} missing`}`);
     if (coverage.entries.length)
         printTable(deps, [
             ["STATUS", "KIND", "NAME", "URL", "SECRET"],

package/dist/client/signing-keys.js

@@ -3,7 +3,7 @@
  * 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 { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { connect, managementClient } from "./target.js";
 export const signingKeysUsage = `  signing-keys list [--tenant <name>]
@@ -15,6 +15,8 @@ export const signingKeysUsage = `  signing-keys list [--tenant <name>]
 const usageError = (message = `Usage:\n${signingKeysUsage}`) => new CliError(message, 2);
 export async function signingKeysCommand(deps, input) {
     const [action, ...args] = input;
+    if (isHelp(action))
+        throw new HelpRequest(`Usage:\n${signingKeysUsage}`);
     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)

package/dist/client/tenant.d.ts

@@ -6,7 +6,7 @@
 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  settings skills [get | put <file|->] [--tenant <name>]\n                                      the most bytes one skill may hold\n  settings limits [get | put <file|->] [--tenant <name>]\n                                      the Runtime limits: sizes, counts and deadlines (record\n                                      entries, request bodies, Environments, model calls, tools)\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, settings artifacts, settings skills and settings limits get print, put takes back. An API key is read from\nstdin, never from the arguments.";
+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|--agents|--all] [--yes] [--tenant <name>]\n                                      clear the Tenant's sessions, its Agents (their vaults,\n                                      disks and sessions) or all its data (the Project link and\n                                      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|manifest|turn] [--id <id>] [--period day|month|total] [--tenant <name>]\n                                      what the model calls used and cost (JSON); --scope\n                                      manifest: the Agents made from agent manifest <id>\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 (scope tenant, manifest with id an\n                                      agent manifest's name, or turn); 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 Agents' environments: limits, stop grace, placement\n  settings artifacts [get | put <file|->] [--tenant <name>]\n                                      the artifact store's limits\n  settings skills [get | put <file|->] [--tenant <name>]\n                                      the most bytes one skill may hold\n  settings limits [get | put <file|->] [--tenant <name>]\n                                      the Runtime limits: sizes, counts and deadlines (record\n                                      entries, request bodies, Agents, model calls, tools)\n  coverage --agent <id> [--tenant <name>] [--json]\n                                      which secret of Agent <id>'s vault each MCP server and\n                                      HTTP tool of its manifest would get\n  mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]\n                                      list a remote MCP server's tools, with Agent <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, settings artifacts, settings skills and settings limits 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;

package/dist/client/tenant.js

@@ -1,4 +1,4 @@
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { keyCommand, keyUsage } from "../stack/keys.js";
 import { printJson, printTable } from "./io.js";
@@ -13,9 +13,10 @@ The Management API of the installation's one Tenant, with a management key: the
 --tenant names (else the linked project's, else the default one), or the installation that
 NYLORUN_RUNTIME_URL and NYLORUN_MANAGEMENT_KEY name.
 
-  reset [--sessions|--environments|--all] [--yes] [--tenant <name>]
-                                      clear the Tenant's sessions, Environments or all its data
-                                      (the Project link and keys stay)
+  reset [--sessions|--agents|--all] [--yes] [--tenant <name>]
+                                      clear the Tenant's sessions, its Agents (their vaults,
+                                      disks and sessions) or all its data (the Project link and
+                                      keys stay)
 ${keyUsage}
 ${signingKeysUsage}
 ${modelsUsage}
@@ -64,16 +65,18 @@ export async function remoteStatus(deps, args) {
     deps.out(`sandbox  ${body.sandbox.backend ?? "none"}`);
     return 0;
 }
-const RESET_USAGE = "nylorun tenant reset [--sessions|--environments|--all] [--yes] [--tenant <name>]";
-const SCOPES = { "--sessions": "sessions", "--environments": "environments", "--all": "all" };
+const RESET_USAGE = "nylorun tenant reset [--sessions|--agents|--all] [--yes] [--tenant <name>]";
+const SCOPES = { "--sessions": "sessions", "--agents": "agents", "--all": "all" };
 /** `nylorun tenant reset`; `--all` asks first. */
 async function reset(deps, args) {
+    if (args.includes("--environments"))
+        throw usageError("--environments is --agents in protocol 16: Environments are Agents. Pass --agents.");
     const flags = parseStackFlags(args, { booleans: ["--yes", ...Object.keys(SCOPES)], values: ["--tenant"], aliases: { "-y": "--yes" } }, RESET_USAGE);
     if (flags.rest.length)
         throw usageError(`Usage: ${RESET_USAGE}`);
     const chosen = Object.keys(SCOPES).filter((flag) => flags.booleans.has(flag));
     if (chosen.length > 1)
-        throw usageError("Pass only one of --sessions, --environments, --all.");
+        throw usageError("Pass only one of --sessions, --agents, --all.");
     const scope = chosen.length ? SCOPES[chosen[0]] : "sessions";
     const { connection, admin } = await tenantClient(deps, flags.values.get("--tenant"));
     if (scope === "all" && !flags.booleans.has("--yes")) {
@@ -98,6 +101,8 @@ async function reset(deps, args) {
  * (application keys only), else on the local Tenant through `nylorun-operate`.
  */
 async function keys(deps, args) {
+    if (isHelp(args[0]))
+        throw new HelpRequest(`Usage:\n${keyUsage}`);
     if (args.includes("--tenant") || !remoteConnection(deps.env, "management"))
         return keyCommand(deps, args);
     const [verb, ...rest] = args;

package/dist/command.d.ts

@@ -3,6 +3,6 @@ export declare function refuseNativeWindows(): void;
 /**
  * Run a command (`nylorun` or `nylo`) and exit once stdout and stderr are flushed: with
  * `process.exitCode` (0 when unset), or after printing a failure's message with its
- * `CliError` exit code (else 1).
+ * `CliError` exit code (else 1); a `HelpRequest`'s usage on stdout, exiting 0.
  */
 export declare function runCommand(main: () => Promise<void>): void;

package/dist/command.js

@@ -1,4 +1,4 @@
-import { CliError } from "./errors.js";
+import { CliError, HelpRequest } from "./errors.js";
 /** Both commands refuse native Windows before acting; WSL2 runs them. */
 export function refuseNativeWindows() {
     if (process.platform === "win32")
@@ -7,10 +7,14 @@ export function refuseNativeWindows() {
 /**
  * Run a command (`nylorun` or `nylo`) and exit once stdout and stderr are flushed: with
  * `process.exitCode` (0 when unset), or after printing a failure's message with its
- * `CliError` exit code (else 1).
+ * `CliError` exit code (else 1); a `HelpRequest`'s usage on stdout, exiting 0.
  */
 export function runCommand(main) {
     void main().then(() => finish(process.exitCode === undefined ? 0 : Number(process.exitCode)), (error) => {
+        if (error instanceof HelpRequest) {
+            console.log(error.message);
+            return finish(0);
+        }
         console.error(error instanceof Error ? error.message : String(error));
         return finish(error instanceof CliError ? error.exitCode : 1);
     });

package/dist/errors.d.ts

@@ -3,3 +3,9 @@ export declare class CliError extends Error {
     readonly exitCode: number;
     constructor(message: string, exitCode?: number);
 }
+/** `--help` or `-h`, which every command and group takes. */
+export declare const isHelp: (arg: string | undefined) => boolean;
+/** A command's usage, asked for with `--help`: printed on stdout, exit 0. */
+export declare class HelpRequest extends CliError {
+    constructor(usage: string);
+}

package/dist/errors.js

@@ -7,3 +7,12 @@ export class CliError extends Error {
         this.name = "CliError";
     }
 }
+/** `--help` or `-h`, which every command and group takes. */
+export const isHelp = (arg) => arg === "--help" || arg === "-h";
+/** A command's usage, asked for with `--help`: printed on stdout, exit 0. */
+export class HelpRequest extends CliError {
+    constructor(usage) {
+        super(usage, 0);
+        this.name = "HelpRequest";
+    }
+}

package/dist/nylo.js

@@ -3,8 +3,8 @@ import "./baseline.js";
 import { runCommand } from "./command.js";
 import { CliError } from "./errors.js";
 /**
- * `nylo` became part of `nylorun`. For one release this command names the `nylorun` command that
- * replaces each of its own and exits 2; a later release removes it.
+ * `nylo` became part of `nylorun`. Until nylorun 0.19, which removes it, this command names the
+ * `nylorun` command that replaces each of its own and exits 2.
  */
 const REPLACEMENTS = {
     status: "nylorun status",
@@ -16,9 +16,9 @@ const REPLACEMENTS = {
 };
 function nyloMessage(argv) {
     const replacement = REPLACEMENTS[argv[0] ?? ""];
-    return replacement
+    return `${replacement
         ? `nylo is part of nylorun now: nylo ${argv[0]} is ${replacement}.`
-        : "nylo is part of nylorun now: run nylorun --help.";
+        : "nylo is part of nylorun now: run nylorun --help."} nylorun 0.19 removes nylo.`;
 }
 runCommand(async () => {
     throw new CliError(nyloMessage(process.argv.slice(2)), 2);

package/dist/stack/commands.d.ts

@@ -51,6 +51,17 @@ interface Flags {
     /** Options that may repeat, in order. */
     lists: Map<string, string[]>;
 }
+/** A command's `usage` line (or block, when it starts indented), as `--help` prints it. */
+export declare const usageText: (usage: string) => string;
+/**
+ * The lines of a group's usage block that start with command `name` (`secrets`, `settings`),
+ * with the lines that continue them, as `--help` prints them.
+ */
+export declare function usageLinesOf(usage: string, name: string): string;
+/**
+ * `args` as the options `allowed` names, and the rest. `--help` or `-h` anywhere is a
+ * `HelpRequest` for `usage`; an option `allowed` does not name is a usage error.
+ */
 export declare function parseStackFlags(args: readonly string[], allowed: {
     booleans?: readonly string[];
     values?: readonly string[];

package/dist/stack/commands.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { compareVersions } from "@nylorun/core/compatibility";
 import { findProjectRoot } from "@nylorun/core/project";
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { credentialsPath, readCredentialsFile, readProjectCredentials, readProjectLink, writeProjectCredentials, writeProjectLink, } from "../project/link.js";
 import { seedTenant } from "../project/seed.js";
 import { readTelemetry, STUDIO_ANALYTICS_ID, TELEMETRY_NOTICE, telemetryDecision, writeTelemetry, } from "../telemetry.js";
@@ -154,6 +154,27 @@ function requireStackFiles(ctx) {
     if (!existsSync(ctx.paths.compose) || !existsSync(ctx.paths.env))
         throw new CliError(`No Tenant ${ctx.name} under ${ctx.paths.root}. Run "nylorun start" first.`, 3);
 }
+/** A command's `usage` line (or block, when it starts indented), as `--help` prints it. */
+export const usageText = (usage) => (/^\s/.test(usage) ? `Usage:\n${usage}` : `Usage: ${usage}`);
+/**
+ * The lines of a group's usage block that start with command `name` (`secrets`, `settings`),
+ * with the lines that continue them, as `--help` prints them.
+ */
+export function usageLinesOf(usage, name) {
+    let keep = false;
+    const lines = usage.split("\n").filter((line) => {
+        if (/^ {2}\S/.test(line))
+            keep = line === `  ${name}` || line.startsWith(`  ${name} `);
+        else if (!/^ {3}/.test(line))
+            keep = false;
+        return keep;
+    });
+    return `Usage:\n${lines.join("\n")}`;
+}
+/**
+ * `args` as the options `allowed` names, and the rest. `--help` or `-h` anywhere is a
+ * `HelpRequest` for `usage`; an option `allowed` does not name is a usage error.
+ */
 export function parseStackFlags(args, allowed, usage) {
     const booleans = new Set();
     const values = new Map();
@@ -161,6 +182,8 @@ export function parseStackFlags(args, allowed, usage) {
     const rest = [];
     for (let index = 0; index < args.length; index += 1) {
         const raw = args[index];
+        if (isHelp(raw))
+            throw new HelpRequest(usageText(usage));
         const arg = allowed.aliases?.[raw] ?? raw;
         // `-` alone is an argument: standard input.
         if (arg === "-" || !arg.startsWith("-")) {

package/dist/stack/compose-file.js

@@ -143,7 +143,7 @@ ${healthcheck("restate")}    restart: unless-stopped
     # Its reachability is in the Tenant's status (GET /v1/tenant, streams.reachable).
     restart: unless-stopped
 
-  rustfs: # the Object store (D35); not published, only the runtime and the gateway hold its credential
+  rustfs: # the Object store; not published, only the runtime and the gateway hold its credential
     image: ${PINNED_IMAGES.rustfs}
     container_name: ${project}-rustfs
     labels: *tenant
@@ -222,7 +222,9 @@ ${healthcheck("gateway")}    restart: unless-stopped
       # Host headers the Runtime accepts: its name on the Compose network, and the
       # published port as clients on this machine address it.
       NYLORUN_ALLOWED_HOSTS: runtime:4000,localhost:\${NYLORUN_PORT},127.0.0.1:\${NYLORUN_PORT}
-      NYLORUN_PUBLIC_URL: http://localhost:\${NYLORUN_PORT}
+      # The URL clients use: webhook URLs and the OAuth resource. Behind a reverse proxy, its URL
+      # (\`NYLORUN_PUBLIC_URL=https://runtime.example.com nylorun start\`).
+      NYLORUN_PUBLIC_URL: \${NYLORUN_PUBLIC_URL:-http://localhost:\${NYLORUN_PORT}}
       NYLORUN_DATABASE_URL: postgres://nylorun:\${NYLORUN_POSTGRES_PASSWORD}@postgres:5432/nylorun
       NYLORUN_RESTATE_INGRESS_URL: http://restate:8080
       NYLORUN_RESTATE_ADMIN_URL: http://restate:9070
@@ -243,7 +245,7 @@ ${healthcheck("gateway")}    restart: unless-stopped
       NYLORUN_HARNESS_LISTEN_PORT: "4200"
       NYLORUN_HARNESS_ALLOWED_HOSTS: runtime:4200${sandboxes ? SANDBOXES_HARNESS_HOST : ""}
       NYLORUN_HARNESS_TOKEN: \${NYLORUN_HARNESS_TOKEN:?run nylorun start}
-      # Traces (R7.2): from the shell that runs \`nylorun start\`. Unset, they are
+      # Traces: from the shell that runs \`nylorun start\`. Unset, they are
       # empty and the Runtime exports nothing. A collector on this machine is host.docker.internal.
       OTEL_EXPORTER_OTLP_ENDPOINT: \${OTEL_EXPORTER_OTLP_ENDPOINT:-}
       OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: \${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-}

package/dist/telemetry.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { CliError } from "./errors.js";
+import { CliError, HelpRequest, isHelp } from "./errors.js";
 /**
  * Studio's anonymous usage analytics. Studio's dashboard reports page views,
  * with every id replaced by `:id`, to this Google Analytics property unless the
@@ -62,6 +62,8 @@ export function telemetryDecision(env, file) {
 const USAGE = "Usage: nylorun local telemetry [status|enable|disable]";
 /** `nylorun local telemetry [status|enable|disable]`. */
 export async function telemetryCommand(args, context) {
+    if (args.some(isHelp))
+        throw new HelpRequest(USAGE);
     const [action = "status", ...rest] = args;
     if (rest.length || !["status", "enable", "disable"].includes(action))
         throw new CliError(USAGE, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nylorun",
-  "version": "0.16.0-beta",
+  "version": "0.18.0-beta",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Set up and run local Nylorun Tenants (Runtime and Studio) with Docker Compose, and act on a Tenant through its Runtime and Management APIs",
@@ -30,23 +30,23 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/admin": "0.18.0-beta",
-    "@nylorun/agents": "0.23.0-beta",
-    "@nylorun/core": "0.23.0-beta"
+    "@nylorun/admin": "0.19.1-beta",
+    "@nylorun/agents": "0.25.0-beta",
+    "@nylorun/core": "0.25.0-beta"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-ai": "1.2.0",
     "@nylorun/agents": "file:../../sdks/agents",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "@types/node": "^26.6.4",
-    "vitest": "^5.0.2"
+    "@types/node": "^26.6.5",
+    "vitest": "^5.0.4"
   },
   "bin": {
     "nylorun": "dist/cli.js",
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.27.0-beta",
-    "studio": "0.26.0-beta"
+    "runtime": "0.29.0-beta",
+    "studio": "0.28.0-beta"
   }
 }

package/dist/client/environment-manifests.d.ts

@@ -1,10 +0,0 @@
-import { type EnvironmentManifestInput } from "@nylorun/agents";
-import type { StackDeps } from "../stack/commands.js";
-export declare const manifestsUsage = "  manifests list [--json]             each environment manifest's latest version\n  manifests get <name> [--version <n>]\n                                      a manifest's latest version (or version n), as JSON\n  manifests versions <name>           its versions, with the Environments made from each\n  manifests save <manifest.json>... [--if-match <n>] [--dry-run]\n                                      save each manifest's next version (a files entry with\n                                      \"from\": a folder beside the file, uploaded by hash);\n                                      --dry-run prints the plan and saves nothing\n  manifests rm <name>                 delete every version (refused while an Environment\n                                      was made from one)";
-/** The manifest in `path`, its `from` folders hashed: the body to save and the bytes to upload. */
-export declare function manifestFrom(path: string): Promise<{
-    manifest: EnvironmentManifestInput;
-    bytes: Record<string, Uint8Array>;
-}>;
-/** `nylorun environments manifests <command> ...` */
-export declare function manifestsCommand(deps: StackDeps, args: readonly string[], usage: string): Promise<number>;