nylorun 0.12.2-beta → 0.13.0-beta

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # nylorun
 
+## 0.13.0-beta
+
+### Minor Changes
+
+- 1345f61: **`nylo` ships in `nylorun`; `@nylorun/cli` is deprecated.** One package runs a project's local Tenant (`nylorun`) and is the Runtime client of the linked installation (`nylo`). MIGRATION.md ("`nylo` ships in `nylorun`") has the details.
+
+  - `nylorun`: a second bin, `nylo` (`npx -p nylorun nylo <command>`), with the same commands, flags, output and exit codes as `@nylorun/cli`'s. The `nylorun` command never loads it. nylorun now depends on `@nylorun/admin`, which `nylo` uses. `nylo configure`'s provider sign-in comes from `@earendil-works/pi-ai` (about 100 MB with its provider SDKs), which is not a dependency: the first `nylo configure` installs the tested version into `~/.nylorun/lib/pi-ai-<version>/` with npm, without install scripts, unless it resolves beside nylorun, so `npx nylorun` stays about 11 MB. `nylorun configure`, `nylorun status --env` and `nylorun doctor sandbox` still exit 2, now naming `npx -p nylorun nylo …`. `nylorun status|reset` (the local Tenant's containers and volumes) and `nylo status|reset` (the Management API) keep their meanings; both usages and the README say which is which.
+  - **Deprecated (`@nylorun/cli`):** its `nylo` prints one line on stderr and runs nylorun's `nylo` with the same arguments and exit code; stdout is unchanged, so `eval "$(npx @nylorun/cli env)"` still works. It depends on `nylorun` only. A later release removes it.
+  - **Breaking (`@nylorun/admin`): the `./project` subpath is removed.** It re-exported `@nylorun/core/project` for `nylo`, which now imports Core directly. Import `@nylorun/core/project` instead.
+  - `@nylorun/create-agent`: `compatibility.json` no longer pins `@nylorun/cli`; the examples run `nylo` from their `nylorun` devDependency.
+
+### Patch Changes
+
+- 554df94: **Fixes for the one client layer.**
+
+  - `@nylorun/admin`: `createAdmin` reads the Project link only in its local-Host step. Explicit `url` and `key`, or `NYLORUN_RUNTIME_URL` with `NYLORUN_MANAGEMENT_KEY`, no longer fail on a `.nylorun/link.json` that cannot be read (EACCES for a root-owned file after `sudo npx nylorun start`, EISDIR); the local-Host step refuses such a link, naming it, as it refuses a broken one (when nothing else names the Host root).
+  - `@nylorun/admin`: a refusal without the Runtime's rejection body takes its code from the status: `invalid_request` (400), `credential_invalid` (401), `not_found` (404), `unsupported_media_type` (415), `internal_error` (5xx), else `request_rejected`; it was always `not_found`. Studio's own answers (`{ message }`, from its server and proxy, such as "This Studio session is invalid or has expired.") keep their message instead of one naming only the request and the status.
+  - `nylorun`: `start` refuses Project or Host root credentials in a newer format than it reads ("Upgrade nylorun"), as it refuses a newer link, instead of replacing them with new keys in its own format.
+
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [554df94]
+- Updated dependencies [1345f61]
+  - @nylorun/admin@0.15.0-beta
+
 ## 0.12.2-beta
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,8 @@
 # nylorun
 
 Sets up and runs local Nylorun Tenants: the Runtime and Studio, in Docker
-Compose, one Tenant per project. It needs nothing in your project; run it with
+Compose, one Tenant per project. Its second command, `nylo`, is the Runtime
+client of the linked installation. It needs nothing in your project; run it with
 `npx` in the project's directory:
 
 ```sh
@@ -14,10 +15,13 @@ and S2, serving exactly that Tenant, and its name is the Tenant's name.
 `nylorun start` in a project creates the project's Tenant (the Runtime creates
 it on its first start) and links the project to it; anywhere else, it starts
 the Tenant `default`. Projects that must not share agents, credentials or
-history run separate Tenants. Agents, sessions and model providers belong to
-the Runtime client, [`@nylorun/cli`](../cli/README.md) (command `nylo`).
-Depends on `@nylorun/core` only among Nylorun packages and never imports
-`@nylorun/runtime`. Vocabulary: [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+history run separate Tenants. The Tenant's status, data, signing keys and model
+provider over its APIs belong to the Runtime client, `nylo`
+([below](#the-runtime-client-nylo)), which works on a remote installation too.
+Depends on `@nylorun/core` and `@nylorun/admin` (for `nylo`) among Nylorun
+packages and never imports `@nylorun/runtime`; the `nylorun` command loads
+neither `nylo` nor `@nylorun/admin`. Vocabulary:
+[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
 
 Prerequisites, installed by the developer (nylorun never downloads them): Node
 24 or newer, and Docker with Compose v2 ([Docker
@@ -59,10 +63,13 @@ nylorun sandbox status [--tenant <name>] [--json]   # pods on a Kubernetes conte
 
 `up` and `down` are the Docker Compose spellings of `start` and `stop`: `down`
 stops the containers and keeps the volumes, so no Tenant data is lost. Removed
-commands exit 2 naming the replacement: `nylorun dev`, `nylorun configure`,
-`nylorun status --env`, `nylorun doctor sandbox` and the MCP OAuth `connect`
+commands exit 2 naming the replacement: `nylorun dev` and the MCP OAuth `connect`
 subcommand of `nylorun mcp` (protocol 10: add a key or a gateway credential to a
 vault instead, and preview the server with `nylorun mcp inspect`).
+`nylorun configure`, `nylorun status --env` and `nylorun doctor sandbox` exit 2
+naming `nylo configure`, `nylo env` and `nylo doctor sandbox`.
+`nylorun status` and `nylorun reset` are not `nylo status` and `nylo reset`: see
+[`status` and `reset`](#status-and-reset-nylorun-or-nylo).
 
 ## Tenants
 
@@ -350,8 +357,95 @@ its files and ports; the next start creates the Tenant anew (with a new id) and
 relinks the project. `nylorun delete <tenant> --yes` removes the Tenant's
 containers, volumes and Host root: the vault key (KEK) and all its data go with it.
 
+## The Runtime client: `nylo`
+
+`nylo` acts on the one Tenant of the linked installation: a local Tenant or any
+Runtime reachable by URL and key. Run it without installing, or in a project
+that has `nylorun` as a devDependency:
+
+```sh
+npx -p nylorun nylo status            # anywhere
+npx nylo status                       # in a project with nylorun installed
+```
+
+Outside such a project, `npx nylo` looks for an npm package named `nylo`, which
+is not this one: use `npx -p nylorun nylo`. The deprecated
+[`@nylorun/cli`](../cli/README.md) runs this `nylo` for one more release.
+
+```sh
+nylo status [--json]                  # the Tenant, its checks and counts
+nylo reset [--sessions|--sandboxes|--all] [--yes]
+nylo access signing-keys …            # the Tenant's signing keys: list, rotate, revoke
+nylo configure                        # set or replace the Tenant's model provider
+nylo env                              # export lines for the linked Project
+nylo doctor sandbox [--json]          # sandbox backend via the Management API
+```
+
+Every command acts on the linked installation: the [Project link and
+credentials](#the-project-link), or `NYLORUN_RUNTIME_URL` and
+`NYLORUN_SERVER_KEY` when the Project has no link. An installation serves one
+Tenant, so nothing selects it. `status`, `reset`, `access`, `configure` and
+`doctor` use the Management API with the Project's management key, or
+`NYLORUN_MANAGEMENT_KEY` (with `NYLORUN_RUNTIME_URL` when there is no link);
+`env` prints the Runtime URL and the application key, for the Runtime API:
+
+```sh
+eval "$(npx -p nylorun nylo env)"
+# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
+```
+
+`nylo` only reads the link, with `@nylorun/core/project`'s reader. It refuses a
+link from an older nylorun (format 0 to 2) and says to run `npx nylorun start`,
+which links the project again. `createClient` in `@nylorun/agents` reads the
+link (or the two variables) too, so the project's `npm run dev` and `npm start`
+need no Nylorun tool.
+
+Local Tenant commands (`up`, `down`, `start`, `stop`, `logs`, `studio`) exit 2
+naming `npx nylorun <command>`. `nylo tenant …` exits 2: `npx nylorun start`
+creates the project's Tenant and the link, and `nylo status|reset` replace
+`nylo tenant status|reset`. `nylo endpoints` was removed with Action endpoints
+(protocol 8: the Runtime runs no code of yours during a session) and exits 2.
+
+### `status` and `reset`: `nylorun` or `nylo`
+
+Both commands have a `status` and a `reset`, which act on different things:
+
+| | `nylorun` | `nylo` |
+| --- | --- | --- |
+| Acts on | the local Tenant on this machine (`--tenant`, `NYLORUN_TENANT` or the link), through Docker and `nylorun-operate` in its runtime container | the linked installation, local or remote, through the Management API with a management key |
+| `status` | the containers, endpoints and Runtime health, and the Tenant's state: it answers when the Tenant is stopped or not open, and says why | the open Tenant's checks, counts and sandbox backend (`GET /v1/tenant`); when the Tenant does not answer it fails and points at `nylorun status` |
+| `reset` | deletes all the Tenant's data: volumes, `tenant/` and the vault key; the next `start` creates it anew, with a new id, and relinks the project | clears the sessions (the default), the sandboxes or all the data (`--all`) after draining work in flight; the Tenant, its keys and the Project link are kept |
+
+`nylo reset --all` asks first; pass `--yes` when not in a terminal.
+`nylorun reset` asks too, or takes `--yes`.
+
+### `nylo configure`
+
+Lists the Tenant's model catalog (`GET /v1/tenant/models`), asks for a provider,
+a model and its sign-in (an API key, or the provider's OAuth), and sets the
+Tenant's model provider (`PUT /v1/tenant/model`). The sign-in flows come from
+`@earendil-works/pi-ai`, about 100 MB with its provider SDKs, which no other
+command needs, so it is not a dependency of nylorun and `npx nylorun` stays
+small. When it does not resolve beside nylorun, the first `nylo configure`
+installs the version nylorun was tested with, with npm and without install
+scripts, into `~/.nylorun/lib/pi-ai-<version>/` (under `NYLORUN_HOME` when that
+is set), and later runs reuse it. Studio's model settings, and `.env` at
+`nylorun start`, set the provider without it.
+
+### `nylo` exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Usage error, or a moved or removed command |
+| 6 | No Runtime at the linked or local URL |
+| 130 / 143 | SIGINT / SIGTERM |
+
 ## Exit codes
 
+These are `nylorun`'s; [`nylo`'s](#nylo-exit-codes) are above.
+
 | Code | Meaning |
 | --- | --- |
 | 0 | Success |
@@ -376,5 +470,9 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 | Studio login expired | `nylorun studio` |
 | Which Studio is which | `nylorun ls` lists each Tenant's Studio URL; `nylorun studio --tenant <name>` opens one signed in |
 | `Tenant … was created by nylorun 0.5` (exit 3) | `nylorun reset --tenant <name>` (its data starts fresh) |
+| `nylo`: no Runtime answers, or the Tenant is not open | `npx nylorun start`, then `npx nylorun status`, which shows the cause and its `repair` |
+| `nylo`: no management key | `npx nylorun start` in the project writes one; elsewhere set `NYLORUN_MANAGEMENT_KEY` |
+| `nylo`: `403 key_role_mismatch` | The key belongs to the other API: a management key for the Management API, an application key for the Runtime API |
+| `nylo`: old Project link refused | `npx nylorun start` in the project |
 
 See [MIGRATION.md](../MIGRATION.md).

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
+import { refuseNativeWindows, runCommand } from "./command.js";
 import { CliError } from "./errors.js";
 import { isStackCommand, keyCommand, keyUsage, mcpCommand, mcpUsage, sandboxCommand, sandboxUsage, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
 const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|sandbox|key|mcp|doctor|telemetry>
@@ -20,12 +21,16 @@ else (outside a project) the default Tenant; NYLORUN_HOME sets its Host root
 
 nylorun sets up and runs local Tenants. "nylorun start" in a project creates the
 project's Tenant and the Project link; anywhere else, it starts the default Tenant.
-Agents, sessions and model providers belong to the Runtime client: npx @nylorun/cli --help`;
-const CLIENT = "npx @nylorun/cli";
-/** Commands that were removed, or moved to the Runtime client (`@nylorun/cli`, command `nylo`). */
+nylorun status and reset act on the local Tenant's containers and volumes on this machine.
+The package's other command, nylo, is the Runtime client of the linked installation: its
+status and reset go through the Management API, and it sets the model provider (nylo --help,
+or npx -p nylorun nylo --help).`;
+/** `nylo`, the Runtime client (this package's second command), run without installing. */
+const CLIENT = "npx -p nylorun nylo";
+/** Commands that were removed, or that are the Runtime client's (`nylo`). */
 const MOVED_TO_CLIENT = {
     dev: "nylorun dev was removed: run `npx nylorun start` in your project (it creates the project's Tenant and the Project link), then your project's `npm run dev`.",
-    configure: `nylorun configure moved to the Runtime client: ${CLIENT} configure`,
+    configure: `nylorun configure is the Runtime client's: ${CLIENT} configure`,
     serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY.",
     runtime: "nylorun runtime was removed: the local Runtime runs in Docker Compose. Use nylorun up|down|status|logs.",
 };
@@ -35,13 +40,12 @@ async function main() {
     const [command, ...args] = process.argv.slice(2);
     if (!command || command === "--help" || command === "-h")
         return void console.log(usage);
-    if (process.platform === "win32")
-        throw new CliError("Nylorun does not run on native Windows. Use WSL2: install Node 24 and Docker (Docker Desktop's WSL integration) inside your WSL distribution and run nylorun there (https://learn.microsoft.com/windows/wsl/install).", 1);
+    refuseNativeWindows();
     const moved = MOVED_TO_CLIENT[command];
     if (moved)
         throw usageError(moved);
     if (command === "status" && args.includes("--env"))
-        throw usageError(`nylorun status --env moved to the Runtime client: ${CLIENT} env`);
+        throw usageError(`nylorun status --env is the Runtime client's: ${CLIENT} env`);
     if (command === "studio") {
         if (args.includes("--local-ui"))
             throw usageError(LOCAL_UI_REMOVED);
@@ -76,7 +80,7 @@ async function main() {
     }
     if (command === "doctor") {
         if (args[0] === "sandbox")
-            throw usageError(`nylorun doctor sandbox moved to the Runtime client: ${CLIENT} doctor sandbox`);
+            throw usageError(`nylorun doctor sandbox is the Runtime client's: ${CLIENT} doctor sandbox`);
         if (args.some((option) => option !== "--json"))
             throw usageError("Usage: nylorun doctor [--json]");
         const { doctorStack } = await import("./doctor.js");
@@ -85,13 +89,4 @@ async function main() {
     }
     throw usageError(usage);
 }
-async function finish(code) {
-    process.exitCode = code;
-    for (const stream of [process.stdout, process.stderr])
-        await new Promise((resolve) => stream.write("", () => resolve()));
-    process.exit(code);
-}
-void main().then(() => finish(process.exitCode === undefined ? 0 : Number(process.exitCode)), (error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    return finish(error instanceof CliError ? error.exitCode : 1);
-});
+runCommand(main);

package/dist/client/access/commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `nylo access`: the linked Tenant's signing keys, which sign capability links and run tokens,
+ * through the Management API with the Project's management key. (Subject tokens, the
+ * access policy, browser keys and revocations left the Runtime in protocol 7.)
+ */
+import type { ManagementClient } from "@nylorun/admin";
+export declare const accessUsage = "nylo access signing-keys <list|rotate|revoke>\n\n  signing-keys list                  list the signing keys\n  signing-keys rotate [--force]      rotate; --force ends outstanding links and run tokens\n  signing-keys revoke <kid>          revoke a previous or standby key";
+export declare function accessCommand(input: readonly string[], client?: () => Promise<ManagementClient>): Promise<void>;

package/dist/client/access/commands.js

@@ -0,0 +1,33 @@
+import { findProjectRoot } from "@nylorun/core/project";
+import { CliError } from "../../errors.js";
+import { linkedConnection, managementClient } from "../project/connection.js";
+export const accessUsage = `nylo access signing-keys <list|rotate|revoke>
+
+  signing-keys list                  list the signing keys
+  signing-keys rotate [--force]      rotate; --force ends outstanding links and run tokens
+  signing-keys revoke <kid>          revoke a previous or standby key`;
+const usageError = (message = accessUsage) => new CliError(message, 2);
+async function linkedClient() {
+    return managementClient(await linkedConnection(findProjectRoot() ?? process.cwd()));
+}
+const print = (value) => console.log(JSON.stringify(value, null, 2));
+export async function accessCommand(input, client = linkedClient) {
+    const [topic, action, ...args] = input;
+    if (topic === "signing-keys") {
+        const keys = async () => (await client()).signingKeys;
+        if (action === "list" && args.length === 0)
+            return print(await (await keys()).list());
+        if (action === "rotate") {
+            const force = args[0] === "--force";
+            if (args.length > (force ? 1 : 0))
+                throw usageError();
+            return print(await (await keys()).rotate({ force }));
+        }
+        if (action === "revoke" && args.length === 1)
+            return print(await (await keys()).revoke(args[0]));
+        throw usageError();
+    }
+    if (topic === "policy" || topic === "keys" || topic === "revoke" || topic === "token")
+        throw usageError(`nylo access ${topic} was removed: the Runtime no longer mints subject tokens or keeps an access policy, browser keys or revocations (protocol 7). Trust your identity provider's tokens with an identity file, and give servers an application key (nylorun key put <id>).`);
+    throw usageError();
+}

package/dist/client/cli.d.ts

@@ -0,0 +1,2 @@
+/** `nylo <command> [...args]`. */
+export declare function main(argv: readonly string[]): Promise<void>;

package/dist/client/cli.js

@@ -0,0 +1,106 @@
+import { findProjectRoot } from "@nylorun/core/project";
+import { CliError } from "../errors.js";
+import { refuseNativeWindows } from "../command.js";
+import { printLinkedEnvExports } from "./project/env.js";
+import { linkedConnection, managementClient } from "./project/connection.js";
+import { accessCommand } from "./access/commands.js";
+import { resetCommand, statusCommand } from "./installation/commands.js";
+const usage = `nylo <status|reset|access|configure|env|doctor>
+
+Runtime client for the linked installation and its one Tenant (the Project link that
+npx nylorun start writes, or NYLORUN_RUNTIME_URL with NYLORUN_SERVER_KEY, and
+NYLORUN_MANAGEMENT_KEY for status, reset, access, configure and doctor):
+  status [--json]                         the Tenant, its checks and counts
+  reset [--sessions|--sandboxes|--all] [--yes]
+                                          clear the Tenant's sessions, sandboxes or all its data
+  access signing-keys list|rotate|revoke  the Tenant's token signing keys (nylo access --help)
+  configure                               set the linked Tenant's model provider
+  env                                     print the linked Project's NYLORUN_* variables as exports
+  doctor sandbox [--json]                 show which sandbox backend this Tenant's Host offers
+
+nylo status and reset go through the Management API, to a local or a remote installation.
+Local Tenants are nylorun's, the other command of this package: npx nylorun start in a
+project creates its Tenant and the Project link, and nylorun status and reset act on the
+local Tenant's containers and volumes.`;
+/** Local Tenant commands, which `nylorun` runs. */
+const LOCAL_COMMANDS = new Set([
+    "up", "down", "start", "stop", "logs", "studio", "runtime", "restart", "run",
+]);
+const TENANT_REMOVED = `nylo tenant was removed: an installation serves one Tenant.
+Run "npx nylorun start" in your project to create its Tenant and the Project link.
+Then use nylo status and nylo reset on the linked installation.`;
+const ENDPOINTS_REMOVED = `nylo endpoints was removed: the Runtime runs no code of yours during a session,
+so there are no Action endpoints. An agent's tools are http() tools and remote MCP servers
+(see MIGRATION.md).`;
+const usageError = (message) => new CliError(message, 2);
+/** `nylo <command> [...args]`. */
+export async function main(argv) {
+    const [command, ...args] = argv;
+    if (!command || command === "--help" || command === "-h")
+        return void console.log(usage);
+    refuseNativeWindows();
+    if (command === "tenant")
+        throw usageError(TENANT_REMOVED);
+    if (command === "status")
+        return await statusCommand(args);
+    if (command === "reset")
+        return await resetCommand(args);
+    if (command === "endpoints")
+        throw usageError(ENDPOINTS_REMOVED);
+    if (command === "access") {
+        if (args[0] === "--help" || args[0] === "-h" || args.length === 0) {
+            const { accessUsage } = await import("./access/commands.js");
+            return void console.log(accessUsage);
+        }
+        return await accessCommand(args);
+    }
+    if (command === "env") {
+        if (args.length)
+            throw usageError("Usage: nylo env");
+        await printLinkedEnvExports(findProjectRoot() ?? process.cwd());
+        return;
+    }
+    if (command === "doctor") {
+        const [topic, ...options] = args;
+        if (topic !== "sandbox" || options.some((option) => option !== "--json"))
+            throw usageError("Usage: nylo doctor sandbox [--json]. Check the local Tenant with npx nylorun doctor.");
+        const { doctorSandbox } = await import("./doctor.js");
+        await doctorSandbox({ json: options.includes("--json") });
+        return;
+    }
+    if (command === "dev")
+        throw usageError('nylorun dev was removed: run "npx nylorun start" once in your project, then your project\'s npm run dev.');
+    if (LOCAL_COMMANDS.has(command))
+        throw usageError(`Local Tenants are nylorun's: npx nylorun ${command}`);
+    if (command === "configure") {
+        for (const arg of args) {
+            if (arg === "--global" || arg === "--db")
+                throw usageError(`${arg} was removed. Use the Runtime Host root (NYLORUN_HOME) and a Project link instead.`);
+            if (arg.startsWith("-"))
+                throw usageError(usage);
+        }
+        if (args.length)
+            throw usageError(usage);
+        const projectRoot = findProjectRoot() ?? process.cwd();
+        const auth = await linkedConnection(projectRoot);
+        const admin = managementClient(auth);
+        // The provider login flows (pi-ai) load only here.
+        const { ConfigurationCancelled, configureProvider, fetchModelCatalog } = await import("./model/configure.js");
+        const { putHostModel } = await import("./model/host-model.js");
+        const controller = new AbortController();
+        const cancel = (signal) => controller.abort(new ConfigurationCancelled(signal));
+        process.once("SIGINT", () => cancel("SIGINT"));
+        process.once("SIGTERM", () => cancel("SIGTERM"));
+        const health = await fetch(`${auth.url}/health`).catch(() => undefined);
+        if (!health?.ok)
+            throw new CliError(`No Runtime is listening at ${auth.url}. Start the local Tenant with "npx nylorun start".`, 6);
+        const catalog = await fetchModelCatalog(admin);
+        const prompted = await configureProvider({
+            signal: controller.signal,
+            catalog,
+        });
+        await putHostModel(admin, prompted);
+        return;
+    }
+    throw usageError(usage);
+}

package/dist/client/doctor.d.ts

@@ -0,0 +1,25 @@
+export type SandboxReport = {
+    preference: string;
+    backend: string | null;
+    isolation?: string;
+    reason?: string;
+    probes: {
+        name: string;
+        isolation: string;
+        available: boolean;
+        reason?: string;
+        version?: string;
+    }[];
+    defaultImage?: string;
+    /** The Tenant's sandbox configuration (Runtimes with Sandboxes v3). */
+    config?: {
+        default: "none" | "virtual" | Record<string, unknown>;
+        limits?: {
+            network?: readonly string[];
+        };
+    };
+};
+/** `nylo doctor sandbox`: Tenant sandbox report via the Management API (F2-4). */
+export declare function doctorSandbox(options: {
+    json: boolean;
+}): Promise<void>;

package/dist/client/doctor.js

@@ -0,0 +1,65 @@
+import { release } from "node:os";
+import { findProjectRoot } from "@nylorun/core/project";
+import { CliError } from "../errors.js";
+import { linkedConnection, managementClient } from "./project/connection.js";
+function platformLine() {
+    const os = process.platform === "darwin"
+        ? "macOS"
+        : process.env.WSL_DISTRO_NAME
+            ? `Linux (WSL: ${process.env.WSL_DISTRO_NAME})`
+            : process.platform;
+    return `${os} (kernel ${release()}) · ${process.arch}`;
+}
+/** The Tenant's sandbox report (`GET /v1/tenant/sandbox`, Management API). */
+async function fetchSandboxReport() {
+    const connection = await linkedConnection(findProjectRoot() ?? process.cwd());
+    return (await managementClient(connection).settings.sandbox.get());
+}
+/** `nylo doctor sandbox`: Tenant sandbox report via the Management API (F2-4). */
+export async function doctorSandbox(options) {
+    let report;
+    try {
+        report = await fetchSandboxReport();
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error
+            ? error.message
+            : `Could not read Tenant sandbox status: ${String(error)}`, 1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ platform: platformLine(), ...report }, null, 2));
+        return;
+    }
+    const rows = [["platform", platformLine()]];
+    for (const probe of report.probes)
+        rows.push([
+            probe.name,
+            `${probe.available ? "✓" : "✗"} ${probe.reason ?? ""}${probe.version ? ` · ${probe.version}` : ""}`,
+        ]);
+    rows.push([
+        "preference",
+        report.preference === "auto"
+            ? "auto (npx nylorun start seeds the Tenant's sandbox.backend from .env NYLORUN_SANDBOX)"
+            : report.preference,
+    ]);
+    if (report.config)
+        rows.push([
+            "default",
+            report.config.default === "none"
+                ? "none: sessions get a sandbox only when opened with one (set a default with PUT /v1/tenant/sandbox)"
+                : report.config.default === "virtual"
+                    ? "virtual: sessions that name no sandbox get one"
+                    : "a Tenant sandbox: sessions that name no sandbox get it",
+        ]);
+    rows.push([
+        "selected",
+        report.backend
+            ? `${report.backend} (${report.isolation} isolation)`
+            : `none: ${report.reason}`,
+    ]);
+    const width = Math.max(...rows.map(([key]) => key.length)) + 2;
+    for (const [key, value] of rows)
+        console.log(`  ${key.padEnd(width)}${value}`);
+    if (report.backend === "virtual")
+        console.log("\n  The virtual shell emulates bash in the Runtime process; it is not a VM boundary.");
+}

package/dist/client/installation/commands.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `nylo status [--json]`: the Tenant, its checks and counts. A Tenant that is not open does not
+ * answer: `npx nylorun status` reports why.
+ */
+export declare function statusCommand(args: readonly string[]): Promise<void>;
+/** `nylo reset [--sessions|--sandboxes|--all] [--yes]`; `--all` asks first. */
+export declare function resetCommand(args: readonly string[]): Promise<void>;

package/dist/client/installation/commands.js

@@ -0,0 +1,80 @@
+/**
+ * `nylo status` and `nylo reset`: the linked installation's one Tenant, through the Management
+ * API (the Project's management key).
+ */
+import { createInterface } from "node:readline/promises";
+import { findProjectRoot } from "@nylorun/core/project";
+import { CliError } from "../../errors.js";
+import { linkedConnection, managementClient } from "../project/connection.js";
+const projectRoot = () => findProjectRoot() ?? process.cwd();
+/**
+ * `nylo status [--json]`: the Tenant, its checks and counts. A Tenant that is not open does not
+ * answer: `npx nylorun status` reports why.
+ */
+export async function statusCommand(args) {
+    const json = args.includes("--json");
+    if (args.some((a) => a !== "--json"))
+        throw new CliError("Usage: nylo status [--json]", 2);
+    const root = projectRoot();
+    const connection = await linkedConnection(root);
+    const admin = managementClient(connection);
+    let body;
+    try {
+        body = await admin.tenant.status();
+    }
+    catch (error) {
+        throw new CliError(`${(error instanceof Error ? error.message : `The Tenant at ${connection.url} is not reachable`).replace(/\.?$/, ".")} Run "npx nylorun status" to see the Tenant's state and why it is not open.`, 1);
+    }
+    if (json) {
+        console.log(JSON.stringify(body, null, 2));
+        return;
+    }
+    console.log(`${body.tenant.name}  ${body.tenant.id}`);
+    console.log(`runtime  ${connection.url}`);
+    console.log(`path     ${body.path}`);
+    console.log(`checks   ${Object.entries(body.checks)
+        .map(([k, v]) => `${k}=${v ? "ok" : "fail"}`)
+        .join(" ")}`);
+    console.log(`counts   sessions=${body.counts.sessions} running=${body.counts.runningSessions} uncertain=${body.counts.uncertainEffects}`);
+    console.log(`sandbox  ${body.sandbox.backend ?? "none"}`);
+}
+const RESET_USAGE = "Usage: nylo reset [--sessions|--sandboxes|--all] [--yes]";
+const SCOPES = { "--sessions": "sessions", "--sandboxes": "sandboxes", "--all": "all" };
+/** `nylo reset [--sessions|--sandboxes|--all] [--yes]`; `--all` asks first. */
+export async function resetCommand(args) {
+    const yes = args.includes("--yes");
+    const flags = args.filter((a) => a !== "--yes");
+    if (flags.some((f) => !(f in SCOPES)) || args.filter((a) => a === "--yes").length > 1)
+        throw new CliError(RESET_USAGE, 2);
+    if (flags.length > 1)
+        throw new CliError("Pass only one of --sessions, --sandboxes, --all.", 2);
+    const scope = flags.length ? SCOPES[flags[0]] : "sessions";
+    const connection = await linkedConnection(projectRoot());
+    const tenant = connection.link?.tenant;
+    const target = tenant ? `Tenant ${tenant} (${connection.url})` : `the Tenant on ${connection.url}`;
+    const admin = managementClient(connection);
+    if (scope === "all" && !yes)
+        await confirmOrThrow(`Reset ALL data of ${target}? The Project link and credentials are kept. [y/N] `);
+    try {
+        await admin.tenant.reset({ scope, activeWork: "drain" });
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error ? error.message : `Tenant reset failed: ${String(error)}`, 1);
+    }
+    console.log(`Reset ${target} (${scope}).`);
+}
+async function confirmOrThrow(prompt) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new CliError("Confirmation required; pass --yes for non-interactive use.", 2);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(prompt)).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes") {
+            throw new CliError("Cancelled.", 1);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/client/model/configure.d.ts

@@ -0,0 +1,58 @@
+import type { Readable, Writable } from "node:stream";
+import type { Credential } from "@earendil-works/pi-ai";
+import type { ManagementClient } from "@nylorun/admin";
+import { CliError } from "../../errors.js";
+/** Exit 130 on SIGINT, 143 on SIGTERM. */
+export declare class ConfigurationCancelled extends CliError {
+    readonly signal: "SIGINT" | "SIGTERM";
+    constructor(signal: "SIGINT" | "SIGTERM");
+}
+export type PromptedModel = {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    /** A custom endpoint's context window and output limit, when given. */
+    settings?: {
+        contextWindow?: number;
+        maxTokens?: number;
+    };
+    auth: Credential;
+};
+export type ModelCatalog = {
+    providers: {
+        id: string;
+        name: string;
+        models: {
+            id: string;
+            name: string;
+        }[];
+        auth?: {
+            apiKey?: unknown;
+            oauth?: unknown;
+        };
+    }[];
+};
+export type Selection = Readonly<{
+    provider: string;
+    model: string;
+    custom?: Readonly<{
+        baseUrl: string;
+    }>;
+}>;
+/** The Tenant's model catalog (`GET /v1/tenant/models`, Management API). */
+export declare function fetchModelCatalog(admin: ManagementClient): Promise<ModelCatalog>;
+export declare function configureProvider(options?: {
+    signal?: AbortSignal;
+    root?: string;
+    input?: Readable;
+    output?: Writable;
+    /** Tenant API catalog from GET /v1/tenant/models. */
+    catalog?: ModelCatalog;
+    /** This installation's stable id, for OAuth flows that need one (OpenAI). */
+    deviceId?: () => string;
+}): Promise<PromptedModel>;
+/**
+ * A stable id for this CLI installation, created on first use under the Host root.
+ * OpenAI's "Sign in with ChatGPT" sends it as the agent host id.
+ */
+export declare function installationId(home?: string): string;