@nylorun/runtime 0.17.0-beta → 0.19.0-beta

package/dist/host/operate.js

@@ -0,0 +1,223 @@
+/**
+ * `nylorun-operate`: the Host's one-shot operator command, run inside the runtime container
+ * (`docker compose exec runtime nylorun-operate …`, `kubectl exec … -- nylorun-operate …`). It
+ * reads the Tenant's database from `NYLORUN_DATABASE_URL`, as the Host does, does one job and
+ * exits. Being able to run it is the authorization: whoever can exec into the container holds
+ * the installation. It never migrates or creates the Tenant: the Host does that.
+ *
+ *   nylorun-operate status [--json]
+ *   nylorun-operate keys list [--json]
+ *   nylorun-operate keys put <id> [--role application|management] [--json]
+ *   nylorun-operate keys rm <id> [--json]
+ *
+ * `status` says whether the Tenant is open and, when it is not, why: from the database (no
+ * Tenant yet, an old layout, a schema newer or older than this Runtime) and from the running
+ * Host's `/ready` on this container's listen port. It needs no key, so it works when the Tenant
+ * cannot open. `keys put` prints the new key once on stdout (with `--json`, the whole
+ * response). Exit codes: 0 done (`status`: the Tenant is open), 1 refused (an id, a role),
+ * 2 the Tenant cannot be opened (`status` still prints it), 64 usage.
+ */
+import { pathToFileURL } from "node:url";
+import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
+import { createPostgresClient } from "../store/postgres/connect.js";
+import { database } from "../store/postgres/db.js";
+import { assertCurrentLayout, expectedSchemaVersion, readSchemaVersion, } from "../store/postgres/migrate.js";
+import { createPostgresSessionStore } from "../store/postgres/store.js";
+import { readTenantEnvelope } from "../store/postgres/tenant.js";
+import { openError, TenantOpenError } from "../tenant/cause.js";
+import { operatorKeys } from "../tenant/operator-keys.js";
+import { RUNTIME_VERSION } from "../version.js";
+import { DEFAULT_CONTAINER_LISTEN_PORT } from "./stack-config.js";
+export const EXIT_REFUSED = 1;
+export const EXIT_TENANT = 2;
+export const EXIT_USAGE = 64;
+const USAGE = `Usage:
+  nylorun-operate status [--json]
+  nylorun-operate keys list [--json]
+  nylorun-operate keys put <id> [--role application|management] [--json]
+  nylorun-operate keys rm <id> [--json]`;
+class Exit extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Runs one command; resolves to the exit code. */
+export async function runOperate(argv, io) {
+    try {
+        if (argv[0] === "status") {
+            const json = argv[1] === "--json";
+            if (argv.length > (json ? 2 : 1))
+                throw new Exit(EXIT_USAGE, USAGE);
+            return await status(io, json);
+        }
+        const command = parse(argv);
+        const url = io.env.NYLORUN_DATABASE_URL;
+        if (!url)
+            throw new Exit(EXIT_TENANT, "NYLORUN_DATABASE_URL is not set: run this inside the runtime container");
+        const sql = createPostgresClient(url, { max: 1 });
+        try {
+            const keys = operatorKeys(await openStore(sql));
+            return await command(keys, io);
+        }
+        finally {
+            await sql.end({ timeout: 5 });
+        }
+    }
+    catch (error) {
+        if (error instanceof Exit) {
+            io.err(error.message);
+            return error.code;
+        }
+        io.err(`nylorun-operate failed: ${error instanceof Error ? error.message : String(error)}`);
+        return EXIT_TENANT;
+    }
+}
+function parse(argv) {
+    const [group, verb, ...rest] = argv;
+    if (group !== "keys")
+        throw new Exit(EXIT_USAGE, USAGE);
+    const json = rest.includes("--json");
+    const args = rest.filter((arg) => arg !== "--json");
+    switch (verb) {
+        case "list":
+            if (args.length > 0)
+                throw new Exit(EXIT_USAGE, USAGE);
+            return async (keys, io) => {
+                const list = await keys.list();
+                if (json)
+                    io.out(JSON.stringify({ keys: list }));
+                else
+                    for (const key of list)
+                        io.out(`${key.id}\t${key.role}\t${key.createdAt}`);
+                return 0;
+            };
+        case "put": {
+            const [id, ...flags] = args;
+            if (!id || id.startsWith("-"))
+                throw new Exit(EXIT_USAGE, USAGE);
+            let role = "application";
+            if (flags.length > 0) {
+                const value = flags[0] === "--role" ? flags[1] : undefined;
+                if (flags.length !== 2 || (value !== "application" && value !== "management"))
+                    throw new Exit(EXIT_USAGE, USAGE);
+                role = value;
+            }
+            return async (keys, io) => {
+                const put = await keys.put(id, role);
+                if ("reason" in put)
+                    throw new Exit(EXIT_REFUSED, put.message);
+                if (json)
+                    io.out(JSON.stringify(put));
+                else {
+                    io.out(put.key);
+                    io.err(`${put.rotated ? "Rotated" : "Created"} ${put.role} key ${put.id}. It is shown this once.`);
+                }
+                return 0;
+            };
+        }
+        case "rm": {
+            const [id] = args;
+            if (!id || args.length !== 1)
+                throw new Exit(EXIT_USAGE, USAGE);
+            return async (keys, io) => {
+                const deleted = await keys.delete(id);
+                if (typeof deleted !== "boolean")
+                    throw new Exit(EXIT_REFUSED, deleted.message);
+                if (json)
+                    io.out(JSON.stringify({ id, deleted }));
+                else
+                    io.err(deleted ? `Deleted key ${id}.` : `There is no key ${id}.`);
+                return 0;
+            };
+        }
+        default:
+            throw new Exit(EXIT_USAGE, USAGE);
+    }
+}
+async function status(io, json) {
+    const tenant = await tenantStatus(io);
+    const report = {
+        version: RUNTIME_VERSION,
+        protocol: { min: HOST_PROTOCOL.min, max: HOST_PROTOCOL.max, features: [...HOST_PROTOCOL.features] },
+        tenant,
+    };
+    if (json)
+        io.out(JSON.stringify(report));
+    else {
+        io.out(`Runtime ${report.version}, protocol ${report.protocol.min}–${report.protocol.max}`);
+        const named = tenant.name ? `${tenant.name} (${tenant.id})` : "none";
+        io.out(`Tenant  ${named}: ${tenant.state}${tenant.cause ? ` (${tenant.cause})` : ""}`);
+        if (tenant.message)
+            io.out(tenant.message);
+    }
+    return tenant.state === "open" ? 0 : EXIT_TENANT;
+}
+/** The Tenant from its database, then from the running Host's `/ready`. */
+async function tenantStatus(io) {
+    const url = io.env.NYLORUN_DATABASE_URL;
+    if (!url)
+        return unavailable(null, "NYLORUN_DATABASE_URL is not set: run this inside the runtime container");
+    const sql = createPostgresClient(url, { max: 1 });
+    let envelope;
+    try {
+        const db = database(sql);
+        await assertCurrentLayout(db);
+        envelope = await readTenantEnvelope(db);
+        if (!envelope)
+            return unavailable(null, "The database holds no Tenant yet: the Runtime creates it when it starts");
+        const version = (await readSchemaVersion(db)) ?? 0;
+        const expected = expectedSchemaVersion();
+        if (version > expected)
+            throw openError("schema-too-new", `The Tenant's schema is at version ${version}, this Runtime's is ${expected}: it was migrated by a newer Runtime`);
+        if (version < expected)
+            return unavailable(envelope, `The Tenant's schema is at version ${version}, this Runtime's is ${expected}: the Runtime migrates it when it starts; if it is running, its log says why it did not`);
+    }
+    catch (error) {
+        if (error instanceof TenantOpenError)
+            return { ...unavailable(envelope ?? null, `${error.message}. Repair: ${error.repair}`), cause: error.code };
+        return unavailable(envelope ?? null, `The database cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+    const port = io.env.NYLORUN_LISTEN_PORT ?? String(DEFAULT_CONTAINER_LISTEN_PORT);
+    const ready = `http://127.0.0.1:${port}/ready`;
+    let answer;
+    try {
+        const response = await (io.fetch ?? fetch)(ready, { signal: AbortSignal.timeout(5000) });
+        answer = (await response.json());
+    }
+    catch {
+        return unavailable(envelope, `The Runtime is not answering at ${ready}: it is stopped or still starting`);
+    }
+    if (answer.checks?.tenant !== true)
+        return unavailable(envelope, "The Runtime is running but has not opened the Tenant: its log names the cause");
+    return { id: envelope.id, name: envelope.name, state: "open" };
+}
+function unavailable(envelope, message) {
+    return { id: envelope?.id ?? null, name: envelope?.name ?? null, state: "unavailable", message };
+}
+/** The Tenant's store, when the Host has created and migrated it to this Runtime's schema. */
+async function openStore(sql) {
+    const db = database(sql);
+    const envelope = await readTenantEnvelope(db).catch((error) => {
+        throw new Exit(EXIT_TENANT, `The Tenant's database cannot be read: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    if (!envelope)
+        throw new Exit(EXIT_TENANT, "The database holds no Tenant yet: start the Runtime first");
+    const version = await readSchemaVersion(db);
+    const expected = expectedSchemaVersion();
+    if (version !== expected)
+        throw new Exit(EXIT_TENANT, `The Tenant's schema is at version ${version ?? "none"}, this Runtime's is ${expected}: start the Runtime to migrate it, or run the Runtime's own image`);
+    return createPostgresSessionStore({ sql, tenantId: envelope.id, schemaVersion: expected });
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+    const code = await runOperate(process.argv.slice(2), {
+        env: process.env,
+        out: (line) => process.stdout.write(`${line}\n`),
+        err: (line) => process.stderr.write(`${line}\n`),
+    });
+    process.exitCode = code;
+}

package/dist/host/stack-config.d.ts

@@ -123,7 +123,7 @@ export interface HarnessServiceConfig {
     pod?: PodHostConfig;
     /** `NYLORUN_GATES_URL`: the gates service its model and MCP calls cross, with run tokens. */
     gatesUrl: string;
-    /** `NYLORUN_HARNESS_ROOT`: its sandboxes, plugin data, home and tmp. Default `/harness`. */
+    /** `NYLORUN_HARNESS_ROOT`: its sandboxes. Default `/harness`. */
     root: string;
     /** `/health` on `127.0.0.1:<NYLORUN_HARNESS_HEALTH_PORT>` (default 4300). */
     healthPort: number;
@@ -149,7 +149,7 @@ export interface StackConfig {
     sandboxes?: SandboxesConfig;
     /**
      * Present when the process runs core or loop and `NYLORUN_GATES_URL` is set: its model calls,
-     * remote MCP calls and Action deliveries cross the gates service. Required for loop in
+     * remote MCP calls and HTTP tool calls cross the gates service. Required for loop in
      * container mode; outside a container (a development Host, tests) the loop may make them in
      * its own process.
      */
@@ -172,19 +172,13 @@ export interface StackConfig {
     listen?: ContainerListen;
     endpoints: StackEndpoints;
     /**
-     * The URL clients use to reach this Host (`NYLORUN_PUBLIC_URL`), reported by
-     * `/v1/admin/status`. In container mode the bind address (`0.0.0.0:4000`)
-     * means nothing outside the container.
+     * The URL clients use to reach this Host (`NYLORUN_PUBLIC_URL`). In container mode the bind
+     * address (`0.0.0.0:4000`) means nothing outside the container.
      */
     publicUrl?: string;
     /**
-     * The operator listener in container mode (`NYLORUN_ADMIN_LISTEN_PORT`, `…_HOST`,
-     * `…_ALLOWED_HOSTS`). Absent: one listener serves the Admin API and the Tenant API.
-     */
-    operator?: ContainerListen;
-    /**
-     * How the Runtime may call Action endpoints: `NYLORUN_ENDPOINT_LOOPBACK=docker-host` (the local
-     * stack: `localhost` means the machine that runs Docker), `NYLORUN_ENDPOINT_PRIVATE`
+     * How the Runtime may call MCP servers and HTTP tools: `NYLORUN_ENDPOINT_LOOPBACK=docker-host`
+     * (the local stack: `localhost` means the machine that runs Docker), `NYLORUN_ENDPOINT_PRIVATE`
      * (`allow` or `refuse`) and `NYLORUN_ENDPOINT_HTTP` (`allow` or `refuse`).
      */
     delivery?: {
@@ -228,6 +222,12 @@ export interface TenantSettings {
      * `trusted-issuers`), read once at boot (`host/main.ts`). Absent: no issuer is trusted.
      */
     identityFile?: string;
+    /**
+     * `NYLORUN_MANAGEMENT_KEY_FILE`: a file holding a management key (64 hex characters), which
+     * the Host registers as the principal `bootstrap` at every start, replacing its key when the
+     * file changed (protocol 8). For installations where no one can run `nylorun-operate`.
+     */
+    managementKeyFile?: string;
 }
 export declare class StackConfigError extends Error {
     constructor(message: string);

package/dist/host/stack-config.js

@@ -225,30 +225,6 @@ function parseListen(env) {
     const allowedHosts = [...new Set([...explicit, ...loopbackForms(port)])];
     return { host, port, allowedHosts };
 }
-function parseAdminListen(env) {
-    const rawPort = read(env, "NYLORUN_ADMIN_LISTEN_PORT");
-    const rawHost = read(env, "NYLORUN_ADMIN_LISTEN_HOST");
-    const rawAllowed = read(env, "NYLORUN_ADMIN_ALLOWED_HOSTS");
-    if (rawPort === undefined) {
-        if (rawHost !== undefined || rawAllowed !== undefined)
-            throw new StackConfigError("NYLORUN_ADMIN_LISTEN_PORT is required with NYLORUN_ADMIN_LISTEN_HOST or NYLORUN_ADMIN_ALLOWED_HOSTS");
-        return undefined;
-    }
-    const host = rawHost ?? DEFAULT_CONTAINER_LISTEN_HOST;
-    if (/\s|\//.test(host))
-        throw new StackConfigError(`NYLORUN_ADMIN_LISTEN_HOST is not an address: ${host}`);
-    const port = parsePort("NYLORUN_ADMIN_LISTEN_PORT", rawPort);
-    const explicit = rawAllowed === undefined
-        ? []
-        : rawAllowed
-            .split(",")
-            .map((entry) => entry.trim())
-            .filter((entry) => entry !== "")
-            .map((entry) => normalizeAllowedHost("NYLORUN_ADMIN_ALLOWED_HOSTS", entry));
-    if (explicit.length === 0 && !isLoopbackAddress(host))
-        throw new StackConfigError(`NYLORUN_ADMIN_ALLOWED_HOSTS is required when NYLORUN_ADMIN_LISTEN_HOST is ${host}: list the Host headers operators send, e.g. runtime:${port},localhost:<published port>`);
-    return { host, port, allowedHosts: [...new Set([...explicit, ...loopbackForms(port)])] };
-}
 const IDENTITY_KEY = /^publickeyv1_[1-9A-HJ-NP-Za-km-z]{32,64}$/;
 function parseIdentityKeys(env) {
     const raw = read(env, "NYLORUN_RESTATE_IDENTITY_KEY");
@@ -271,15 +247,12 @@ export function parseStackConfig(env, argv) {
     // The image sets NYLORUN_LISTEN_*: only the API's processes read them.
     const servesApi = services.has("core") || services.has("loop");
     const listen = servesApi ? parseListen(env) : undefined;
-    const operator = servesApi ? parseAdminListen(env) : undefined;
     const gates = services.has("gates") || services.has("keys") ? parseGates(env) : undefined;
     const egress = services.has("egress") ? parseEgress(env) : undefined;
-    // The gates service's clients: the loop's model and tool calls, and core's endpoint pings.
+    // The gates service's clients: the loop's model and tool calls.
     const modelGate = servesApi ? parseModelGate(env) : undefined;
     // The keys service is the gateway's unless NYLORUN_KEYS_URL names another listener.
     const keys = servesApi ? (parseKeysEndpoint(env) ?? modelGate) : undefined;
-    if (operator && listen && operator.port === listen.port)
-        throw new StackConfigError("NYLORUN_ADMIN_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT");
     if (services.has("loop") && listen && !modelGate)
         throw new StackConfigError("NYLORUN_GATES_URL is required for the loop service in a container: model calls go through the gates service (the gateway container), so the loop never holds a model credential. Set NYLORUN_GATES_URL and NYLORUN_GATES_TOKEN (`nylorun start` sets both)");
     const rawPacking = read(env, "NYLORUN_PACKING");
@@ -326,9 +299,8 @@ export function parseStackConfig(env, argv) {
     const harnessListener = harnessMode === "remote" || sandboxes
         ? parseHarnessListener(env, harnessMode === "remote")
         : undefined;
-    if (harnessListener &&
-        [listen?.port, operator?.port].includes(harnessListener.listen.port))
-        throw new StackConfigError("NYLORUN_HARNESS_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT and NYLORUN_ADMIN_LISTEN_PORT");
+    if (harnessListener && listen?.port === harnessListener.listen.port)
+        throw new StackConfigError("NYLORUN_HARNESS_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT");
     const delivery = parseDelivery(env);
     const tenant = servesApi ? parseTenant(env) : undefined;
     const objectStore = parseObjectStore(env);
@@ -346,7 +318,6 @@ export function parseStackConfig(env, argv) {
         ...(harnessMode ? { harnessMode } : {}),
         ...(harnessListener ? { harnessListener } : {}),
         ...(sandboxes ? { sandboxes } : {}),
-        ...(operator ? { operator } : {}),
         ...(delivery ? { delivery } : {}),
         ...(tenant ? { tenant } : {}),
         ...(objectStore ? { objectStore } : {}),
@@ -379,10 +350,12 @@ function parseTenant(env) {
     if (id !== undefined && !isTenantId(id))
         throw new StackConfigError(`NYLORUN_TENANT_ID must be a Tenant id (tn_ and 26 Crockford characters), not ${id}`);
     const identityFile = read(env, "NYLORUN_IDENTITY_FILE");
+    const managementKeyFile = read(env, "NYLORUN_MANAGEMENT_KEY_FILE");
     return {
         ...(id ? { id } : {}),
         name: read(env, "NYLORUN_TENANT_NAME") ?? "default",
         ...(identityFile ? { identityFile } : {}),
+        ...(managementKeyFile ? { managementKeyFile } : {}),
     };
 }
 const GATES_TOKEN = /^[0-9a-f]{64,}$/i;

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export type { ResolverConfig } from "./vault/sources.js";
 export type { RuntimeAgent } from "./contracts.js";
 export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./media.js";
 export type { RuntimeModelAdapter } from "./contracts.js";
-export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./host/environment.js";
+export { baselineEnvironment, hostProcessEnvironment, } from "./host/environment.js";
 export type { HostProcessPathInputs } from "./host/environment.js";
 export type { HostConfigFile, HostCredentialsFile, } from "./host/config.js";

package/dist/index.js

@@ -4,4 +4,4 @@ export { parseIdentityFile, IdentityFileError, } from "./tenant/identity-file.js
 export { createTrustedIssuers, } from "./tenant/issuers.js";
 export { scriptedModel, gatewayModel } from "./core/provider.js";
 export { IMAGE_MEDIA_TYPES, MAX_IMAGE_BYTES, decodeImageBase64, validateImageBytes, } from "./media.js";
-export { baselineEnvironment, hostProcessEnvironment, tenantChildEnvironment, } from "./host/environment.js";
+export { baselineEnvironment, hostProcessEnvironment, } from "./host/environment.js";

package/dist/infra/workers.d.ts

@@ -3,7 +3,7 @@
  *
  * | Services | Serves | `execution.start` |
  * | --- | --- | --- |
- * | `core` | Tenant API, Admin API, SSE | **never**: wakes, timers and sweep arming go through Restate's ingress, which needs no Worker endpoint |
+ * | `core` | Runtime and Management APIs, SSE | **never**: wakes, timers and sweep arming go through Restate's ingress, which needs no Worker endpoint |
  * | `loop` | the Restate endpoint (`NylorunSession.advance`, `NylorunTenant.sweep`, timers) | yes |
  * | `core,loop` | both (the local stack's `runtime` container) | yes |
  *

package/dist/keys/keys.js

@@ -1,8 +1,8 @@
 /**
  * The keys seam (blueprint §14, F4.2): everything that needs the vault key. Vault writes that
  * touch a secret (creating and rotating a credential, setting and selecting the host model;
- * rotation and selection decrypt the old secret first) and all token signing (subject and
- * delivery tokens, signing-key rotation) run here, whole, so the process that calls them never
+ * rotation and selection decrypt the old secret first) and all token signing (capability
+ * links, run and host tokens, signing-key rotation) run here, whole, so the process that calls them never
  * holds the key or a private signing key.
  *
  * MCP OAuth connect (F9-D14) runs here too: discovery, registration, the code exchange and the