@nylorun/runtime 0.17.0-beta → 0.19.1-beta

package/dist/api/http/routes/vaults.js

@@ -6,8 +6,8 @@ import { VaultError } from "../../../vault/error.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
-/** Every vault route, and starting an MCP OAuth connect: an application key acting for no one. */
-const APPLICATION = { credentials: ["application"], scopes: "never" };
+/** The Management API's vault routes (`/v1/tenant/vaults`): a management key. */
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
 /**
  * The OAuth callback: a browser sent back by the authorization server, with no credential and no
  * protocol header. The `state` it carries is the grant.
@@ -30,10 +30,11 @@ const body = (schema) => ({
 });
 const vaultId = z.object({ vaultId: z.string() });
 const credentialId = vaultId.extend({ credentialId: z.string() });
-export function vaultRoutes(api) {
-    tenantRoute(api, APPLICATION, {
+/** The vault routes under `base` (`/v1/tenant/vaults`). */
+function vaultRoutesAt(api, base, access) {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults",
+        path: `${base}`,
         tags: ["Vaults"],
         summary: "Create a vault",
         description: "With `scope: \"installation\"` the installation's own vault, owned by `installation`, which any session may attach; or a vault of one person (`ownerUserId`), which only that person's sessions attach.",
@@ -46,9 +47,9 @@ export function vaultRoutes(api) {
         const request = CreateVaultRequestSchema.parse(await readJson(c.req.raw));
         return jsonResponse(200, await c.env.tenant.vault.createVault(request));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults",
+        path: `${base}`,
         tags: ["Vaults"],
         summary: "List vaults",
         description: "The installation vaults, after the vaults of `ownerUserId` when it names a person.",
@@ -68,9 +69,9 @@ export function vaultRoutes(api) {
             }),
         });
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}",
+        path: `${base}/{vaultId}`,
         tags: ["Vaults"],
         summary: "Get a vault",
         request: { params: vaultId },
@@ -78,9 +79,9 @@ export function vaultRoutes(api) {
     }, async (c) => {
         return jsonResponse(200, await c.env.tenant.vault.getVault(c.req.param("vaultId")));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "delete",
-        path: "/v1/vaults/{vaultId}",
+        path: `${base}/{vaultId}`,
         tags: ["Vaults"],
         summary: "Delete a vault and its credentials",
         request: { params: vaultId },
@@ -88,9 +89,9 @@ export function vaultRoutes(api) {
     }, async (c) => {
         return jsonResponse(200, await c.env.tenant.vault.deleteVault(c.req.param("vaultId")));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults/{vaultId}/credentials",
+        path: `${base}/{vaultId}/credentials`,
         tags: ["Vaults"],
         summary: "Add a credential",
         description: "A bearer token or OAuth tokens, bound to the URLs a tool may send them to.",
@@ -100,9 +101,9 @@ export function vaultRoutes(api) {
         const request = CreateCredentialRequestSchema.parse(await readJson(c.req.raw));
         return jsonResponse(200, await c.env.tenant.keys.createCredential(c.req.param("vaultId"), request));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}/credentials",
+        path: `${base}/{vaultId}/credentials`,
         tags: ["Vaults"],
         summary: "List a vault's credentials",
         request: { params: vaultId },
@@ -112,9 +113,9 @@ export function vaultRoutes(api) {
             credentials: await c.env.tenant.vault.listCredentials(c.req.param("vaultId")),
         });
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Get a credential",
         request: { params: credentialId },
@@ -122,9 +123,9 @@ export function vaultRoutes(api) {
     }, async (c) => {
         return jsonResponse(200, await c.env.tenant.vault.getCredential(c.req.param("vaultId"), c.req.param("credentialId")));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Rotate a credential's secret",
         request: { params: credentialId, body: body(RotateCredentialRequest) },
@@ -136,9 +137,9 @@ export function vaultRoutes(api) {
         const request = RotateCredentialRequestSchema.parse(await readJson(c.req.raw));
         return jsonResponse(200, await c.env.tenant.keys.rotateCredential(c.req.param("vaultId"), c.req.param("credentialId"), request));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "delete",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Delete a credential",
         request: { params: credentialId },
@@ -146,9 +147,9 @@ export function vaultRoutes(api) {
     }, async (c) => {
         return jsonResponse(200, await c.env.tenant.vault.deleteCredential(c.req.param("vaultId"), c.req.param("credentialId")));
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults/{vaultId}/oauth/start",
+        path: `${base}/{vaultId}/oauth/start`,
         tags: ["Vaults"],
         summary: "Start an MCP OAuth connect",
         description: "Signs the installation in to the remote MCP server at `url` (declared as `server`) and stores its OAuth credential, bound to `url`, in this installation vault. The Runtime discovers the server's authorization server (RFC 9728, RFC 8414), registers itself (RFC 7591) unless `clientId` names a registered client, and answers the URL to open in a browser; the sign-in returns to `GET /v1/oauth/callback` within `expiresAt`. The callback URL is `NYLORUN_PUBLIC_URL` + `/v1/oauth/callback`, or this request's own origin when the Host has no public URL. Application keys acting for no one only. `oauth_client_required` when the server offers no registration and no `clientId` was given.",
@@ -171,6 +172,9 @@ export function vaultRoutes(api) {
             redirectUri: `${base}${OAUTH_CALLBACK_PATH}`,
         }));
     });
+}
+export function vaultRoutes(api) {
+    vaultRoutesAt(api, "/v1/tenant/vaults", MANAGEMENT);
     tenantRoute(api, CALLBACK, {
         method: "get",
         path: OAUTH_CALLBACK_PATH,

package/dist/api/openapi.d.ts

@@ -1,19 +1,18 @@
 /**
- * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
- *
- * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
- *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
- *   and attached to each release.
- * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
- *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ * The Runtime's two OpenAPI 3.2 documents, generated from the routes as declared for serving
+ * (protocol 8): the Runtime API (`runtimeDocument`: `/openapi/runtime.json`, alias
+ * `/openapi.json`, `@nylorun/runtime/openapi.json`) and the Management API (`managementDocument`:
+ * `/openapi/management.json`, `@nylorun/runtime/management-openapi.json`). Both are attached to
+ * each release. Each has described tags in the order a developer uses them; the Runtime API
+ * groups them (`x-tagGroups`).
  *
  * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
  * the environment: the same Runtime makes the same document.
  */
 import { OpenApiGeneratorV32 } from "@asteasolutions/zod-to-openapi";
 type OpenApiDocument = ReturnType<OpenApiGeneratorV32["generateDocument"]>;
-/** The Tenant API's document. */
-export declare function tenantDocument(): OpenApiDocument;
-/** The Admin API's document. */
-export declare function adminDocument(): OpenApiDocument;
+/** The Runtime API's document: `/openapi/runtime.json` and `/openapi.json`. */
+export declare function runtimeDocument(): OpenApiDocument;
+/** The Management API's document: `/openapi/management.json`. */
+export declare function managementDocument(): OpenApiDocument;
 export {};

package/dist/api/openapi.js

@@ -1,11 +1,10 @@
 /**
- * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
- *
- * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
- *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
- *   and attached to each release.
- * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
- *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ * The Runtime's two OpenAPI 3.2 documents, generated from the routes as declared for serving
+ * (protocol 8): the Runtime API (`runtimeDocument`: `/openapi/runtime.json`, alias
+ * `/openapi.json`, `@nylorun/runtime/openapi.json`) and the Management API (`managementDocument`:
+ * `/openapi/management.json`, `@nylorun/runtime/management-openapi.json`). Both are attached to
+ * each release. Each has described tags in the order a developer uses them; the Runtime API
+ * groups them (`x-tagGroups`).
  *
  * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
  * the environment: the same Runtime makes the same document.
@@ -13,7 +12,6 @@
 import { OpenAPIRegistry, OpenApiGeneratorV32, } from "@asteasolutions/zod-to-openapi";
 import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
 import { HealthResponseSchema, ReadyResponseSchema } from "@nylorun/core/contracts";
-import { createAdminApi } from "../host/admin-api.js";
 import { RUNTIME_VERSION } from "../version.js";
 import { tenantApi } from "./http/app.js";
 const PROTOCOL = {
@@ -27,7 +25,10 @@ const bearer = (description, bearerFormat) => ({
     ...(bearerFormat ? { bearerFormat } : {}),
     description,
 });
-/** `/health`, `/ready` and `/openapi.json`: what every listener answers without a key. */
+/**
+ * `/health`, `/ready` and the documents: what every listener answers without a key. The
+ * `/openapi.json` alias is served but left out of the documents.
+ */
 function hostRoutes() {
     const registry = new OpenAPIRegistry();
     const route = (config) => registry.registerPath(config);
@@ -49,7 +50,7 @@ function hostRoutes() {
         path: "/ready",
         tags: ["Host"],
         summary: "Check the Runtime is ready",
-        description: "The listeners, the Tenant (open), Postgres, Restate and S2.",
+        description: "The listener, the Tenant (open), Postgres, Restate and S2, and the open Tenant's harnesses.",
         responses: {
             200: {
                 description: "Ready",
@@ -60,72 +61,296 @@ function hostRoutes() {
     });
     route({
         method: "get",
-        path: "/openapi.json",
+        path: "/openapi/runtime.json",
+        tags: ["Host"],
+        summary: "Get the Runtime API's document",
+        description: "This document. `/openapi.json` is the same.",
+        responses: { 200: { description: "The Runtime API's OpenAPI document" } },
+    });
+    route({
+        method: "get",
+        path: "/openapi/management.json",
         tags: ["Host"],
-        summary: "Get this document",
-        responses: { 200: { description: "The Tenant API's OpenAPI document" } },
+        summary: "Get the Management API's document",
+        responses: { 200: { description: "The Management API's OpenAPI document" } },
     });
     return registry;
 }
 function tenantSchemes(registry) {
-    registry.registerComponent("securitySchemes", "applicationKey", bearer("An application key of the Tenant: an operator key (`PUT /v1/admin/keys/{id}`), or Studio's key, derived from the admin key. With `Nylorun-Subject` and `Nylorun-Scopes`, it acts for that person, narrowed to those scopes. Never accepted from a browser (`Origin`)."));
+    registry.registerComponent("securitySchemes", "applicationKey", bearer("An application key of the Tenant (`PUT /v1/tenant/keys/{keyId}`), or Studio's key, derived from the admin key. With `Nylorun-Subject` and `Nylorun-Scopes`, it acts for that person, narrowed to those scopes. Never accepted from a browser (`Origin`)."));
+    registry.registerComponent("securitySchemes", "managementKey", bearer("A management key of the Tenant (role `management`): it reaches the Management API (`/v1/tenant/*`) and `/v1/me`, as itself, never for a subject. Issued only on the Tenant's machine (`nylorun-operate keys put <id> --role management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`. Never accepted from a browser (`Origin`)."));
     registry.registerComponent("securitySchemes", "issuerToken", bearer("A JWT from a trusted issuer of the Host's identity file (Host feature `trusted-issuers`): one person, with the issuer's scopes, agents and sandbox grants, until it expires. Accepted from servers and browsers alike; CORS is the operator's proxy's.", "JWT"));
-    registry.registerComponent("securitySchemes", "deliveryToken", bearer("The delivery token the Runtime signs each Action delivery with (`Nylorun-Signature`), sent back by the Action endpoint. It reaches only that Action's heartbeat, result and sandbox routes, while that delivery is current, for at most 15 minutes.", "JWT"));
 }
-let tenant;
-let admin;
-/** The Tenant API's document. */
-export function tenantDocument() {
-    if (tenant)
-        return tenant;
+const RUNTIME_TAGS = [
+    {
+        name: "Agents",
+        group: "Agents",
+        description: "The agents a Tenant can run: put a definition, list what is there. In `@nylorun/agents`.",
+        operations: ["PUT /v1/agents/{agentId}", "GET /v1/agents"],
+    },
+    {
+        name: "Definition files",
+        group: "Agents",
+        description: "The files a definition names by the SHA-256 of their bytes (each skill's folder): upload each once before putting the definition, which is refused while it names one the Runtime does not hold (`definition_files_missing`). `saveAgent` in `@nylorun/agents` does both.",
+        operations: ["PUT /v1/files/{file}", "HEAD /v1/files/{file}"],
+    },
+    {
+        name: "Sessions API",
+        group: "Sessions",
+        description: "A conversation with an agent: open a session, send commands, follow its events, read its history. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/sessions/{sessionId}",
+            "GET /v1/sessions",
+            "GET /v1/sessions/{sessionId}",
+            "POST /v1/sessions/{sessionId}/commands",
+            "GET /v1/sessions/{sessionId}/events",
+            "GET /v1/sessions/{sessionId}/items",
+            "GET /v1/sessions/{sessionId}/manifest",
+            "GET /v1/sessions/{sessionId}/usage",
+            "GET /v1/sessions/{sessionId}/calls/model",
+            "POST /v1/sessions/{sessionId}/sandbox/{tool}",
+        ],
+    },
+    {
+        name: "AG-UI",
+        group: "Sessions",
+        description: "The same sessions through AG-UI: a thread is one session per person, agent and thread, and each run is a turn.",
+        operations: [
+            "POST /v1/ag-ui/agents/{agentId}",
+            "GET /v1/ag-ui/agents/{agentId}/threads/{threadId}/events",
+            "GET /v1/ag-ui/agents/{agentId}/threads/{threadId}/messages",
+            "POST /v1/ag-ui/agents/{agentId}/threads/{threadId}/cancel",
+        ],
+    },
+    {
+        name: "A2A",
+        group: "Sessions",
+        description: "The same sessions through Agent2Agent: a context is one session per subject, agent and `contextId`, and a task is one turn. The card is how an A2A client finds the agent.",
+        operations: ["GET /v1/a2a/agents/{agentId}/card", "POST /v1/a2a/agents/{agentId}"],
+    },
+    {
+        name: "Sandboxes",
+        group: "Sandboxes",
+        description: "Isolated machines an agent works in: create or find one, watch its lifecycle, stop, reset or delete it. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/sandboxes/{sandboxId}",
+            "GET /v1/sandboxes",
+            "GET /v1/sandboxes/{sandboxId}",
+            "GET /v1/sandboxes/{sandboxId}/events",
+            "POST /v1/sandboxes/{sandboxId}/stop",
+            "POST /v1/sandboxes/{sandboxId}/reset",
+            "DELETE /v1/sandboxes/{sandboxId}",
+        ],
+    },
+    {
+        name: "Artifacts",
+        group: "Artifacts",
+        description: "Files and folders agents and people produce, versioned, with short-lived capability links to share them. In `@nylorun/agents`.",
+        operations: [
+            "POST /v1/artifacts",
+            "GET /v1/artifacts",
+            "GET /v1/artifacts/{artifactId}",
+            "POST /v1/artifacts/{artifactId}/versions",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/content",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/tree",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/files/{path}",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/diff",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/zip",
+            "POST /v1/artifacts/{artifactId}/links",
+            "GET /v1/artifact-links/{token}",
+            "DELETE /v1/artifacts/{artifactId}",
+        ],
+    },
+    {
+        name: "Service",
+        group: "Service",
+        description: "Check a Runtime is up and speaks your protocol, ask who your credential is, and read the public keys of the tokens it signs. `/health`, `/ready`, the JWKS and the documents need no key.",
+        operations: [
+            "GET /health",
+            "GET /ready",
+            "GET /v1/me",
+            "GET /v1/access/jwks",
+            "GET /openapi/runtime.json",
+        ],
+    },
+];
+const MANAGEMENT_TAGS = [
+    {
+        name: "Tenant",
+        description: "The Tenant's status, and seeding or resetting it. `admin.tenant` in `@nylorun/admin`.",
+        operations: [
+            "GET /v1/tenant",
+            "PUT /v1/tenant/config/seed",
+            "POST /v1/tenant/reset",
+            "GET /v1/me",
+            "GET /openapi/management.json",
+        ],
+    },
+    {
+        name: "Application keys",
+        description: "The keys app servers call the Runtime API with: create, rotate, list and delete them. Management keys come only from the Tenant's machine. `admin.keys`.",
+        operations: ["GET /v1/tenant/keys", "PUT /v1/tenant/keys/{keyId}", "DELETE /v1/tenant/keys/{keyId}"],
+    },
+    {
+        name: "Models",
+        description: "Model providers, their credentials, the model the Tenant uses, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
+        operations: [
+            "GET /v1/tenant/models",
+            "GET /v1/tenant/providers",
+            "GET /v1/tenant/model",
+            "PUT /v1/tenant/model",
+            "PUT /v1/tenant/model/selection",
+            "GET /v1/tenant/usage",
+            "GET /v1/tenant/calls/model",
+            "GET /v1/tenant/budgets",
+            "PUT /v1/tenant/budgets",
+        ],
+    },
+    {
+        name: "Vaults",
+        description: "The installation's credentials for agents' tools: API keys and MCP OAuth connections. Sessions attach a vault by id. `admin.vaults`.",
+        operations: [
+            "POST /v1/tenant/vaults",
+            "GET /v1/tenant/vaults",
+            "GET /v1/tenant/vaults/{vaultId}",
+            "DELETE /v1/tenant/vaults/{vaultId}",
+            "POST /v1/tenant/vaults/{vaultId}/credentials",
+            "GET /v1/tenant/vaults/{vaultId}/credentials",
+            "GET /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "POST /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "DELETE /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "POST /v1/tenant/vaults/{vaultId}/oauth/start",
+            "GET /v1/oauth/callback",
+        ],
+    },
+    {
+        name: "Signing keys",
+        description: "The keys the Runtime signs capability links and run tokens with; their public halves are the Runtime API's JWKS. `admin.signingKeys`.",
+        operations: [
+            "GET /v1/tenant/signing-keys",
+            "POST /v1/tenant/signing-keys/rotate",
+            "POST /v1/tenant/signing-keys/{kid}/revoke",
+        ],
+    },
+    {
+        name: "Settings",
+        description: "The Tenant's sandbox and artifact settings. `admin.settings`.",
+        operations: [
+            "GET /v1/tenant/sandbox",
+            "PUT /v1/tenant/sandbox",
+            "GET /v1/tenant/artifacts",
+            "PUT /v1/tenant/artifacts",
+        ],
+    },
+];
+const METHODS = ["get", "head", "put", "post", "delete", "patch"];
+const SERVERS = [
+    {
+        url: "{origin}",
+        description: "A Runtime: a local Tenant (`nylorun start`), or where yours runs",
+        variables: { origin: { default: "http://localhost:8787" } },
+    },
+];
+/** The `#/components/schemas/…` names `value` refers to, followed through `schemas`. */
+function referencedSchemas(value, schemas) {
+    const found = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            if (key === "$ref" && typeof child === "string" && child.startsWith("#/components/schemas/")) {
+                const name = child.slice("#/components/schemas/".length);
+                if (!found.has(name)) {
+                    found.add(name);
+                    walk(schemas[name]);
+                }
+            }
+            else
+                walk(child);
+        }
+    };
+    walk(value);
+    return found;
+}
+/** One reference document: `tags`' operations of `all`, in their order, with what they use. */
+function document(all, tags, info) {
+    const paths = {};
+    for (const tag of tags)
+        for (const name of tag.operations) {
+            const [method, path] = name.split(" ");
+            const operation = all.paths?.[path]?.[method.toLowerCase()];
+            if (!operation)
+                throw new Error(`The Runtime has no operation ${name}`);
+            (paths[path] ??= {})[method.toLowerCase()] = { ...operation, tags: [tag.name] };
+        }
+    const schemas = (all.components?.schemas ?? {});
+    const used = referencedSchemas(paths, schemas);
+    const schemes = new Set();
+    for (const item of Object.values(paths))
+        for (const operation of Object.values(item))
+            for (const requirement of (operation.security ?? []))
+                for (const scheme of Object.keys(requirement))
+                    schemes.add(scheme);
+    const groups = [...new Set(tags.flatMap((tag) => (tag.group ? [tag.group] : [])))];
+    return {
+        ...all,
+        info: { ...all.info, ...info },
+        tags: tags.map((tag) => ({ name: tag.name, description: tag.description })),
+        ...(groups.length
+            ? {
+                "x-tagGroups": groups.map((group) => ({
+                    name: group,
+                    tags: tags.filter((tag) => tag.group === group).map((tag) => tag.name),
+                })),
+            }
+            : {}),
+        paths,
+        components: {
+            ...all.components,
+            schemas: Object.fromEntries(Object.entries(schemas).filter(([name]) => used.has(name))),
+            securitySchemes: Object.fromEntries(Object.entries(all.components?.securitySchemes ?? {}).filter(([name]) => schemes.has(name))),
+        },
+    };
+}
+let built;
+/** Both reference documents, built once from every route; throws when one is left out. */
+function documents() {
+    if (built)
+        return built;
     const host = hostRoutes();
     tenantSchemes(host);
-    tenant = new OpenApiGeneratorV32([
+    const all = new OpenApiGeneratorV32([
         ...host.definitions,
         ...tenantApi().openAPIRegistry.definitions,
     ]).generateDocument({
         openapi: "3.2.0",
-        info: {
-            title: "Nylorun Runtime: Tenant API",
-            version: RUNTIME_VERSION,
-            description: "Agents, sessions and their events, vaults, access and the Tenant's settings. A Runtime serves one Tenant: its URL is the Tenant's, and no request names it. Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields.",
-            "x-nylorun-protocol": PROTOCOL,
-        },
-        servers: [
-            {
-                url: "{origin}",
-                description: "A Runtime: a local Tenant (`nylorun start`), or where yours runs",
-                variables: { origin: { default: "http://localhost:8787" } },
-            },
-        ],
+        info: { title: "Nylorun Runtime", version: RUNTIME_VERSION, "x-nylorun-protocol": PROTOCOL },
+        servers: SERVERS,
     });
-    return tenant;
+    const listed = new Set([...RUNTIME_TAGS, ...MANAGEMENT_TAGS].flatMap((tag) => tag.operations));
+    for (const [path, item] of Object.entries(all.paths ?? {}))
+        for (const method of METHODS)
+            if (item[method] && !listed.has(`${method.toUpperCase()} ${path}`))
+                throw new Error(`${method.toUpperCase()} ${path} is in no reference tag (api/openapi.ts)`);
+    built = {
+        runtime: document(all, RUNTIME_TAGS, {
+            title: "Nylorun Runtime API",
+            description: "For developers: agents, sessions (with AG-UI and A2A), sandboxes and artifacts, through `@nylorun/agents`. Every Tenant serves it on its one URL, beside the Management API (`/openapi/management.json`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields: an application key (servers) or a trusted issuer's token (browsers and apps).",
+        }),
+        management: document(all, MANAGEMENT_TAGS, {
+            title: "Nylorun Management API",
+            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun key put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
+        }),
+    };
+    return built;
 }
-/** The Admin API's document. */
-export function adminDocument() {
-    if (admin)
-        return admin;
-    // Only the routes' declarations are read: nothing is served from this app.
-    const api = createAdminApi({
-        status: () => Promise.reject(new Error("Not served")),
-        shutdown: () => { },
-    });
-    api.openAPIRegistry.registerComponent("securitySchemes", "adminKey", bearer("The Host's admin key (`host-credentials.json`). Never a Tenant bearer."));
-    admin = new OpenApiGeneratorV32(api.openAPIRegistry.definitions).generateDocument({
-        openapi: "3.2.0",
-        info: {
-            title: "Nylorun Runtime: Admin API",
-            version: RUNTIME_VERSION,
-            description: "The Host's status, its Tenant's state, shutdown and the Tenant's operator keys, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
-            "x-nylorun-protocol": PROTOCOL,
-        },
-        servers: [
-            {
-                url: "{origin}",
-                description: "The operator listener: a local Tenant's, or where yours runs",
-                variables: { origin: { default: "http://localhost:8788" } },
-            },
-        ],
-    });
-    return admin;
+/** The Runtime API's document: `/openapi/runtime.json` and `/openapi.json`. */
+export function runtimeDocument() {
+    return documents().runtime;
+}
+/** The Management API's document: `/openapi/management.json`. */
+export function managementDocument() {
+    return documents().management;
 }

package/dist/artifacts/links.js

@@ -2,7 +2,7 @@
  * Capability links (protocol 6): a short-lived URL that opens one artifact version with no
  * other credential, for UIs, `<img>` tags and sharing. The token in the path is an ES256 JWT
  * (`typ: nylorun-artifact+jwt`) signed with the Tenant's current signing key by the keys
- * service, like delivery tokens: `sub` is the artifact, `ver` the version, `aud`
+ * service, like run tokens: `sub` is the artifact, `ver` the version, `aud`
  * `nylorun-artifact`, and it lives at most `ARTIFACT_LINK_MAX_TTL_SECONDS` (`TOKEN_TTL_MAX_SECONDS`,
  * so a key rotation never revokes a live link). A link opens nothing once its artifact
  * is deleted. A folder's link (F8.2) opens its zip, or with a `path` claim one of its files.