nylorun 0.17.0-beta → 0.18.1-beta

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # nylorun
 
+## 0.18.1-beta
+
+### Patch Changes
+
+- Pin studio to the tested release.
+
+## 0.18.0-beta
+
+### Minor Changes
+
+- eeb6294: Session usage as one ledger (protocol 18). The usage ledger keeps each model call's cost by token kind (uncached input, cache read, cache write, output) at the prices the adapter applied (migration 0037). For a protocol 18 client, `GET /v1/sessions/{id}/calls/model` returns each call's `startedAt`, `endedAt` and `usage.costSplit` (null for a call recorded before), and `GET /v1/sessions/{id}/usage` adds `costSplit` with `splitCalls`, and the calls' durations added up as `modelTimeMs` with `timedCalls`. A protocol 16 or 17 client reads usage as before. Studio's Usage tab is rebuilt on them: a Session card with one tokens bar and a ledger of tokens and cost by kind adding up to a total row, then the model calls grouped by turn with the same columns (cached, uncached, output, total, time, cost), and a row menu whose View event opens the call's event in the Events tab.
+
+### Patch Changes
+
+- ed08ba8: Public text names no internal roadmap codes: the OpenAPI documents' descriptions, the type comments of `@nylorun/core`, `@nylorun/agents` and `@nylorun/admin`, and the CLI's help, README and generated compose file. A Runtime test fails when either OpenAPI document names one.
+- ed08ba8: `nylo` and the deprecated `@nylorun/cli` name the release that removes them, nylorun 0.19, where they said "one release": `nylo`'s message ends "nylorun 0.19 removes nylo.", and `@nylorun/cli`'s stderr line, description and README say nylorun 0.19 removes both.
+- ed08ba8: `--help` (or `-h`) works on every command and subcommand: it prints that command's own usage on stdout and exits 0, where `nylorun migrate v8 --help`, `nylorun tenant budgets --help` and others exited 2 with "Unknown option --help", and `nylorun tenant settings --help` printed the usage of `budgets`, `tool-policy` and `coverage` too. `nylorun --help` lists every `agents` command (`pin`, `track`, `restart`, `triggers`, `runs` and `memories` were missing) and `migrate v8 --name`, and the README lists `agents pin`, `track`, `restart`, `put --dry-run`, `fork --label` and `list --outdated`.
+- ed08ba8: Webhook URLs name the Runtime's public URL. A trigger's `webhookUrl` is at `NYLORUN_PUBLIC_URL`, else the origin the request reached, so behind a reverse proxy that rewrites `Host` to `localhost:<port>` it is the proxy's URL, not `http://localhost:<port>`; the Runtime API's `401` challenges name it too. `nylorun start` passes `NYLORUN_PUBLIC_URL` from its shell to the runtime container (default `http://localhost:<port>`).
+- Pin core to the tested release.
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [eeb6294]
+- Updated dependencies [ed08ba8]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.25.0-beta
+  - @nylorun/agents@0.25.0-beta
+  - @nylorun/admin@0.19.1-beta
+
 ## 0.17.0-beta
 
 ### Minor Changes
@@ -11,7 +46,7 @@
 
   The SDK has `client.agentManifests`, `client.agents` and `composeManifest(dir)` for three-file authoring; the CLI has `nylorun apply`, `nylorun agent-manifests`, `nylorun agents` and `nylorun migrate v8`; Studio has an Agents screen, an Agent page and an Agent manifests screen. See MIGRATION.md.
 
-- 4fa160d: Agent memory, storage and API (track T5, D72). An agent manifest's `harness.memory` (`access`: `read_write` or `read_only`; `instructions`, at most 4,096 characters) turns on the Agent's memory: Markdown files under `/memories` it keeps across sessions, wakes and upgrades. The Runtime keeps them in Postgres (`memories`, `memory_versions`, migration 0036) with a version per change and who made it. `GET /v1/agents/{id}/memories` lists them (`pathPrefix`), `GET`, `PUT` (whole content, with an optional `contentSha256` precondition: `409 memory_conflict`) and `DELETE /v1/agents/{id}/memories/{path}` read, write and delete one (or a folder), and `GET /v1/agents/{id}/memory_versions` and `.../memory_versions/{versionId}` page the versions. A fork copies the memories (the fork plan adds `memories`); a delete removes them. `@nylorun/core` adds `memoryPathOf`, `memoryDescriptionOf` and the memory contracts; new Runtime limits `memoryBytes` (100 KB) and `memoriesPerAgent` (10,000); new error code `memory_conflict`. The SDK adds `client.agents.memories`; the CLI adds `nylorun agents memories ls|cat|put|rm|versions`. The model's `memory` tool arrives in the next steps of T5.
+- 4fa160d: Agent memory, storage and API (track T5, D72). An agent manifest's `harness.memory` (`access`: `read_write` or `read_only`; `instructions`, at most 4,096 characters) turns on the Agent's memory: Markdown files under `/memories` it keeps across sessions, wakes and upgrades. The Runtime keeps them in Postgres (`memories`, `memory_versions`, migration 0036) with a version per change and who made it. `GET /v1/agents/{id}/memories` lists them (`pathPrefix`), `GET`, `PUT` (whole content, with an optional `contentSha256` precondition: `409 memory_conflict`) and `DELETE /v1/agents/{id}/memories/{path}` read, write and delete one (or a folder), and `GET /v1/agents/{id}/memory_versions` and `.../memory_versions/{versionId}` page the versions. A fork copies the memories (the fork plan adds `memories`); a delete removes them. `@nylorun/core` adds `memoryPathOf`, `memoryDescriptionOf` and the memory contracts; new Runtime limits `memoryBytes` (100 KiB) and `memoriesPerAgent` (10,000); new error code `memory_conflict`. The SDK adds `client.agents.memories`; the CLI adds `nylorun agents memories ls|cat|put|rm|versions`. The model's `memory` tool arrives in the next steps of T5.
 - 9e60e40: Protocol 17, a queue per session (track T4, D76). A message sent while the session's turn runs or waits is queued (`{status: "queued", queuedMessageId, position}`, `message.queued`) and starts the next turn when this one ends, with every queued message, each its own user message (`queue.taken`); a cancel ends the turn, not the queue. `delivery: "reject"` keeps the refusal, now `409 session_busy`, and a protocol 16 client's messages default to it, so the Host serves protocol 16 and 17. The queue holds at most the Runtime limit `sessionQueuedMessages` (`429 queue_full`), and session reads count `queuedMessages`. Our engine takes `{kind: "messages", messages}` as a turn's input. The SDK's `input` and `inputParts` take `delivery`, and the CLI's `sessions send` takes `--reject-if-busy`. See MIGRATION.md.
 - f85483d: Triggers (track T4, D74). An agent manifest's `runtime.triggers` declares `schedule` (cron with an IANA `timezone`) and `at` triggers, each with the session its runs go to (a session id, opened on the first run, or `new` for a session per run) and its prompt. They start active with a new Agent, fire on a durable timer per trigger with Postgres as the truth (one late fire after downtime, never a backfill, a fixed jitter per trigger), and each fire is a run (`started`, `queued`, `skipped` or `failed`, with a reason) at `GET /v1/agents/{id}/runs`. A schedule adds at most one queued message to a busy session. `GET /v1/agents/{id}/triggers` and `POST .../triggers/{triggerId}/pause`, `/resume` and `/run` (with an `Idempotency-Key`); Agent reads add `nextWakeAt`, and the Agent's stream adds `agent.run`, `agent.trigger_paused` and `agent.trigger_resumed`. New Runtime limits: `triggersPerAgent`, `triggerMinIntervalMs` and `triggerRunRetentionMs` (with floors), `triggerRunsPerHour`, `triggerJitterPercent`, `triggerJitterMaxMs`, `triggerPromptChars`; Host tuning `triggers.lateGraceMs` and `triggers.intervalCheckFires`. The SDK's `client.agents` adds `triggers`, `pauseTrigger`, `resumeTrigger`, `runTrigger` and `runs`; the CLI adds `nylorun agents triggers` and `nylorun agents runs`.
 - ae54de7: Webhook triggers (track T4, D75). A `webhook: "standard-webhooks"` trigger has an endpoint, `POST /v1/webhooks/{endpointId}`, an anonymous, unversioned route that takes any body up to the new Runtime limit `webhookBodyBytes` and verifies Standard Webhooks (`webhook-id`, `webhook-timestamp` within the Host's `triggers.webhookToleranceMs`, `webhook-signature`) in the keys service, which alone opens the trigger's sealed secret; anything else is `401` and writes nothing. A delivery runs the trigger once per `webhook-id` (`202 {runId, status}`); a paused trigger answers a signed one `409 trigger_paused`. `POST /v1/agents/{id}/triggers/{triggerId}/secret` makes or replaces the `whsec_` secret, shown once (`agent.trigger_secret_rotated`); trigger reads show `webhookUrl` and `secretSet`. The payload reaches the model under the trigger's prompt in a labelled `<trigger-payload>` block. The SDK adds `agents.rotateWebhookSecret`, and the CLI `nylorun agents triggers new-secret`.

package/README.md

@@ -38,7 +38,8 @@ npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the Tenan
 ## Commands
 
 The installation's lifecycle is a handful of top-level commands; everything else
-is in a group that follows the API it uses, and each group has its own `--help`.
+is in a group that follows the API it uses. Every group and command takes `--help`
+(or `-h`), which prints its own usage and exits 0.
 
 ```sh
 nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset] [--restate-ui]
@@ -56,16 +57,19 @@ nylorun apply [<dir>...] [--dry-run] [--if-match <n>]   # plan, then save each f
 nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]   # the three files from a v7 manifest; reads no Runtime
 nylorun agent-manifests list [--json]       # name, latest version, runtime kind, harness, Agents
 nylorun agent-manifests get <name>[@<n>] | versions <name> | rm <name>
-nylorun agents list [--state <s>] [--manifest <name>] [--label <key=value>]... [--behind] [--limit <n>] [--cursor <c>] [--json]   # --behind: on an older manifest version
+nylorun agents list [--state <s>] [--manifest <name>] [--label <key=value>]... [--outdated] [--limit <n>] [--cursor <c>] [--json]   # --outdated (or --behind): moving to another manifest version
 nylorun agents get|stop|reset|rm|snapshot|versions <id>
-nylorun agents put <id> --manifest <name[@n]> [--owner <user>] [--label <key=value>]...   # name tracks its latest version, name@n pins one
-nylorun agents fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--dry-run]   # onto a new manifest version
+nylorun agents put <id> --manifest <name[@n]> [--owner <user>] [--label <key=value>]... [--dry-run]   # name tracks its latest version, name@n pins one; --dry-run prints the move
+nylorun agents pin <id> <version>   # move it to that manifest version, and keep it there
+nylorun agents track <id>           # move it to its manifest's latest version, and with each save
+nylorun agents restart <id> [--retry]   # apply the version it waits to start on now; --retry: the one that failed to start
+nylorun agents fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--label <key=value>]... [--dry-run]   # onto a new manifest version
 nylorun agents restore <id> <version|latest>
 nylorun agents delete-version <id> <version>
 nylorun agents events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]
 nylorun agents triggers list <id> | pause|resume <id> <trigger> | run <id> <trigger> [--idempotency-key <k>] | new-secret <id> <trigger>
 nylorun agents runs <id> [--trigger <id>] [--limit <n>] [--cursor <c>]   # what each trigger fire came to
-nylorun agents memories ls|cat|put|rm|versions <id> [<path>] [<file|->]   # its memories (track T5); put seeds one
+nylorun agents memories ls|cat|put|rm|versions <id> [<path>] [<file|->]   # its memories; put seeds one
 nylorun agents secrets list|get|put|rm <id> [<name>] [<secret.json|->]   # put without a file: a slot's value on stdin
 nylorun sessions list [--agent <id>] [--manifest <name>] [--status <s>] [--owner <user>] [--limit <n>] [--cursor <c>] [--json]
 nylorun sessions create --agent <id> --owner <user> [--id <id>] [--info <json>]   # a session on Agent <id>
@@ -126,8 +130,8 @@ apply`; `nylorun configure` is `nylorun tenant models set`. `nylorun dev`,
 are gone.
 
 The package's second command, `nylo`, was the Runtime client until nylorun took
-its commands. For one release it names the `nylorun` command that replaced each
-of its own and exits 2:
+its commands. Until nylorun 0.19, which removes it, it names the `nylorun`
+command that replaced each of its own and exits 2:
 
 | `nylo` | `nylorun` |
 | --- | --- |

package/dist/cli.js

@@ -2,7 +2,7 @@
 import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { refuseNativeWindows, runCommand } from "./command.js";
-import { CliError } from "./errors.js";
+import { CliError, HelpRequest, isHelp } from "./errors.js";
 import { defaultStackDeps, stackCommand, stackUsage, studioCommand } from "./stack/index.js";
 const usage = `nylorun <command>
 
@@ -16,15 +16,16 @@ Agent manifests:
   apply [<dir>...] [--dry-run] [--if-match <n>]
                                       save the agent manifest each folder's agent.manifest.json
                                       describes, with the files it names (Runtime API)
-  migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--out <dir>]
+  migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]
                                       write the three manifest files from an agent manifest v7
                                       and an environment manifest v1 (reads no Runtime)
 
 Groups, each with its own --help:
   agent-manifests  list | get | versions | rm
                                       the Tenant's agent manifests (Runtime API)
-  agents        list | get | put | fork | stop | reset | rm | snapshot | restore
-                versions | delete-version | events | secrets
+  agents        list | get | put | pin | track | restart | fork | stop | reset | rm |
+                snapshot | restore | versions | delete-version | events | secrets |
+                triggers | runs | memories
                                       the Tenant's Agents, made from saved manifests; sessions
                                       run on them (Runtime API)
   sessions      list | create | get | send | approve | respond | cancel | watch | history
@@ -183,6 +184,8 @@ async function main() {
         const [topic, ...options] = args;
         if (topic === "sandbox") {
             const usage = "Usage: nylorun doctor sandbox [--tenant <name>] [--json]";
+            if (options.some(isHelp))
+                throw new HelpRequest(usage);
             const tenantAt = options.indexOf("--tenant");
             const tenant = tenantAt < 0 ? undefined : options[tenantAt + 1];
             const rest = options.filter((_, index) => index !== tenantAt && index !== tenantAt + 1);
@@ -195,8 +198,11 @@ async function main() {
             });
             return;
         }
+        const usage = "Usage: nylorun doctor [--json] | nylorun doctor sandbox [--tenant <name>] [--json]";
+        if (args.some(isHelp))
+            throw new HelpRequest(usage);
         if (args.some((option) => option !== "--json"))
-            throw usageError("Usage: nylorun doctor [--json] | nylorun doctor sandbox [--tenant <name>] [--json]");
+            throw usageError(usage);
         const { doctorStack } = await import("./doctor.js");
         process.exitCode = await doctorStack({ json: args.includes("--json"), env });
         return;

package/dist/client/agents.d.ts

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

package/dist/client/agents.js

@@ -1,4 +1,6 @@
 import { parseAgentManifestRef } from "@nylorun/core/contracts";
+import { HelpRequest, isHelp } from "../errors.js";
+import { usageLinesOf } from "../stack/commands.js";
 import { readSecret, readText } from "./io.js";
 import { integerFlag, labelsOf, parseFlags, positional, printCursor, printJson, printTable, readJson, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
 export const agentsUsage = `nylorun agents <command>
@@ -56,7 +58,7 @@ NYLORUN_TOKEN).
                                       what each fire came to (started, queued, skipped,
                                       failed), newest first, as JSON
   memories ls <id> [--prefix <folder>] [--limit <n>] [--cursor <c>]
-                                      its memories (track T5) by path, as JSON
+                                      its memories by path, as JSON
   memories cat <id> <path>            one memory's content
   memories put <id> <path> <file|->   write a memory whole (seed it), from a file or stdin
   memories rm <id> <path>             delete a memory, or every memory in a folder
@@ -292,6 +294,8 @@ async function events(deps, args) {
 }
 async function secrets(deps, args) {
     const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "secrets"));
     if (verb === "list" || verb === "ls") {
         const usage = "nylorun agents secrets list <id>";
         const flags = parseFlags(rest, {}, usage);
@@ -342,6 +346,8 @@ async function secrets(deps, args) {
 /** `nylorun agents triggers <list|pause|resume|run> …` (track T4). */
 async function triggers(deps, args) {
     const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "triggers"));
     if (verb === "list" || verb === "ls") {
         const usage = "nylorun agents triggers list <id>";
         const flags = parseFlags(rest, {}, usage);
@@ -380,6 +386,8 @@ async function triggers(deps, args) {
 /** `nylorun agents memories <ls|cat|put|rm|versions> …` (track T5). */
 async function memories(deps, args) {
     const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(usageLinesOf(agentsUsage, "memories"));
     const pageOf = (flags) => {
         const limit = flags.values.get("--limit");
         if (limit !== undefined && !/^[1-9]\d*$/.test(limit))

package/dist/client/mcp.js

@@ -8,7 +8,7 @@
  * removed in protocol 10, and says so.
  */
 import { PROTOCOL_HEADER, PROTOCOL_VERSION } from "@nylorun/core/compatibility";
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { connect } from "./target.js";
 export const mcpUsage = `  mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]
@@ -151,6 +151,8 @@ function oneLine(text) {
 /** `nylorun tenant mcp <inspect|connect> ...` */
 export async function mcpCommand(deps, args) {
     const [sub, ...rest] = args;
+    if (isHelp(sub))
+        throw new HelpRequest(`Usage:\n${mcpUsage}`);
     if (sub === "inspect")
         return inspect(deps, rest);
     if (sub === "connect")

package/dist/client/models.js

@@ -5,7 +5,7 @@
  * for CI. A key is never an argument.
  */
 import { randomUUID } from "node:crypto";
-import { CliError } from "../errors.js";
+import { CliError, HelpRequest, isHelp } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
 import { printJson, printTable, readSecret } from "./io.js";
 import { connect, managementClient } from "./target.js";
@@ -140,6 +140,8 @@ async function select(deps, args) {
 /** `nylorun tenant models <verb> ...` */
 export async function modelsCommand(deps, args) {
     const [verb, ...rest] = args;
+    if (isHelp(verb))
+        throw new HelpRequest(`Usage:\n${modelsUsage}`);
     if (verb === "catalog" || verb === "providers" || verb === "get")
         return read(deps, verb, rest);
     if (verb === "set")

package/dist/client/runtime.d.ts

@@ -10,7 +10,7 @@ export declare const RUNTIME_FLAGS: {
 export declare const runtimeFlagsUsage: string;
 export declare const usageError: (message: string) => CliError;
 export type Flags = ReturnType<typeof parseStackFlags>;
-/** `args` parsed with the Runtime flags added to `allowed`. */
+/** `args` parsed with the Runtime flags added to `allowed`; `--help` names them too. */
 export declare function parseFlags(args: readonly string[], allowed: {
     booleans?: readonly string[];
     values?: readonly string[];

package/dist/client/runtime.js

@@ -5,16 +5,18 @@
  */
 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 { CliError, HelpRequest, isHelp } from "../errors.js";
+import { parseStackFlags, usageText } 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`. */
+/** `args` parsed with the Runtime flags added to `allowed`; `--help` names them too. */
 export function parseFlags(args, allowed, usage) {
+    if (args.some(isHelp))
+        throw new HelpRequest(`${usageText(usage)}\n\n${runtimeFlagsUsage}`);
     return parseStackFlags(args, {
         booleans: allowed.booleans ?? [],
         values: [...RUNTIME_FLAGS.values, ...(allowed.values ?? [])],

package/dist/client/sessions.js

@@ -258,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.js

@@ -1,6 +1,6 @@
 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>]
@@ -77,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")
@@ -85,7 +87,7 @@ 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> [--tenant <name>] [--json]";
 /**

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.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";
@@ -101,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.17.0-beta",
+  "version": "0.18.1-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,9 +30,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@nylorun/admin": "0.19.0-beta",
-    "@nylorun/agents": "0.24.0-beta",
-    "@nylorun/core": "0.24.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": "1.2.0",
@@ -46,7 +46,7 @@
     "nylo": "dist/nylo.js"
   },
   "nylorun": {
-    "runtime": "0.28.0-beta",
-    "studio": "0.27.0-beta"
+    "runtime": "0.29.0-beta",
+    "studio": "0.29.0-beta"
   }
 }