@nylorun/runtime 0.14.0-beta → 0.15.1-beta

package/dist/host/app.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
-import { checkCompatibility, HOST_PROTOCOL, isTenantId, PROTOCOL_HEADER, PUBLISHABLE_KEY_HEADER, TENANT_HEADER, tenantOfPublishableKey, } from "@nylorun/core/compatibility";
+import { checkCompatibility, HOST_PROTOCOL, PROTOCOL_HEADER, PUBLISHABLE_KEY_HEADER, TENANT_HEADER, tenantOfPublishableKey, } from "@nylorun/core/compatibility";
 import { RUNTIME_VERSION } from "../version.js";
 import { findTenantRoute } from "../api/http/app.js";
 import { tenantDocument } from "../api/openapi.js";
@@ -69,13 +69,13 @@ export function createHostApp(options) {
             });
         if (pathname === "/ready") {
             const listener = options.listening();
-            const discovery = module.started;
+            const tenant = module.ready;
             const infra = await options.readiness?.();
-            const ready = listener && discovery && !options.closing() && (infra?.ok ?? true);
+            const ready = listener && tenant && !options.closing() && (infra?.ok ?? true);
             return jsonResponse(ready ? 200 : 503, {
                 status: ready ? "ready" : "not_ready",
                 service: "nylorun-runtime",
-                checks: { listener, discovery, ...infra?.checks },
+                checks: { listener, tenant, ...infra?.checks },
             });
         }
         // This API's own description: public, as the npm package that ships it.
@@ -93,36 +93,32 @@ export function createHostApp(options) {
                 return opaqueNotFoundResponse();
             return await options.admin(c.req.raw, { incoming, outgoing });
         }
-        // Tenant routes: header pattern → protocol → resolve → the Tenant. The Tenant is named by
-        // `Nylorun-Tenant`, by the publishable key in `Nylorun-Key`, or by both when they agree.
-        const invalid = (message) => rejectedResponse(400, "invalid_request", message);
+        // Tenant routes: key pattern → protocol → the Tenant → selection → the Tenant's routes.
         const keyHeader = headerValue(incoming, PUBLISHABLE_KEY_HEADER);
         const keyTenant = keyHeader === undefined ? undefined : tenantOfPublishableKey(keyHeader);
         if (keyHeader !== undefined && keyTenant === undefined)
-            return invalid(`${PUBLISHABLE_KEY_HEADER} header is malformed`);
+            return rejectedResponse(400, "invalid_request", `${PUBLISHABLE_KEY_HEADER} header is malformed`);
         const tenantHeader = headerValue(incoming, TENANT_HEADER);
-        const named = tenantHeader === undefined || tenantHeader.trim() === "" ? undefined : tenantHeader;
-        if (named === undefined && keyTenant === undefined)
-            return invalid(`${TENANT_HEADER} header is required`);
-        if (named !== undefined && !isTenantId(named))
-            return invalid(`${TENANT_HEADER} header is malformed`);
-        if (named !== undefined && keyTenant !== undefined && named !== keyTenant)
-            return invalid(`${PUBLISHABLE_KEY_HEADER} and ${TENANT_HEADER} name different Tenants`);
-        const tenantId = (named ?? keyTenant);
-        c.set("tenantId", tenantId);
+        const named = tenantHeader === undefined || tenantHeader.trim() === "" ? undefined : tenantHeader.trim();
         if (!protocolAccepted(headerValue(incoming, PROTOCOL_HEADER)))
             return protocolRejectedResponse();
-        const resolution = await module.resolve(tenantId);
+        const resolution = await module.resolve();
         if (resolution.kind !== "open") {
-            if (resolution.kind === "quarantined")
-                logger.warn("tenant_quarantined", {
-                    tenantId,
-                    code: resolution.quarantine.code,
-                    repair: resolution.quarantine.repair,
+            if (resolution.cause)
+                logger.warn("tenant_unavailable", {
+                    code: resolution.cause.code,
+                    repair: resolution.cause.repair,
                 });
             return opaqueNotFoundResponse();
         }
-        return await resolution.handle.fetch(c.req.raw, { incoming, outgoing });
+        const { handle } = resolution;
+        const tenantId = handle.envelope.id;
+        // A protocol 4 client names the Tenant; a publishable key carries one. Either naming
+        // another Tenant (or a malformed header) reached the wrong installation.
+        if ((named !== undefined && named !== tenantId) || (keyTenant !== undefined && keyTenant !== tenantId))
+            return opaqueNotFoundResponse();
+        c.set("tenantId", tenantId);
+        return await handle.fetch(c.req.raw, { incoming, outgoing });
     });
     app.onError((error, c) => {
         const status = error.status;

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

@@ -1,7 +1,7 @@
 import type { HostConfigFile } from "./config.js";
 import type { Logger, TenantConfig } from "../tenant/types.js";
 /**
- * Builds a TenantConfig for `openTenantRuntime`.
+ * Builds the TenantConfig of the Host's Tenant for `openTenantRuntime`.
  * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
  * setting overrides it when the Tenant opens (I1, A18).
  */

package/dist/host/config-for.js

@@ -1,14 +1,14 @@
 import { tenantPaths } from "../tenant/paths.js";
 import { tenantChildEnvironment } from "./environment.js";
 /**
- * Builds a TenantConfig for `openTenantRuntime`.
+ * Builds the TenantConfig of the Host's Tenant for `openTenantRuntime`.
  * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
  * setting overrides it when the Tenant opens (I1, A18).
  */
 export function configForFactory(options) {
     const { baseline } = options;
     return (id) => {
-        const tenant = tenantPaths(options.hostRoot, id);
+        const tenant = tenantPaths(options.hostRoot);
         const sandboxBackend = "auto";
         return {
             tenantId: id,

package/dist/host/create-host.d.ts

@@ -39,18 +39,18 @@ export interface CreateHostOptions {
     operator?: OperatorListen;
     /**
      * Infrastructure readiness (`infra/readiness.ts`). `/ready` adds its checks
-     * and answers 503 while it reports not ok. Default: listener and discovery
-     * only.
+     * and answers 503 while it reports not ok. Default: the listener and the
+     * Tenant only.
      */
     readiness?: () => Promise<{
         ok: boolean;
         checks: Record<string, boolean>;
     }>;
     /**
-     * Shutdown steps around closing the Tenants. `close()` runs them whatever asked for it
+     * Shutdown steps around closing the Tenant. `close()` runs them whatever asked for it
      * (SIGTERM in `host/main.ts`, `POST /v1/admin/host/shutdown`): the listener stops, then
-     * `beforeTenants` (stop the Worker so no advance starts on a closing Tenant), the Tenants
-     * close, then `afterTenants` (end the infrastructure clients). A failing step is logged
+     * `beforeTenants` (stop the Worker so no advance starts on the closing Tenant), the Tenant
+     * closes, then `afterTenants` (end the infrastructure clients). A failing step is logged
      * and shutdown goes on.
      */
     shutdown?: {

package/dist/host/create-host.js

@@ -5,7 +5,7 @@ import { AdminStatusSchema } from "@nylorun/core/contracts";
 import { adminDocument } from "../api/openapi.js";
 import { createAdminApi } from "./admin-api.js";
 import { createHostApp } from "./app.js";
-import { EXIT_NON_LOOPBACK, EXIT_PORT_IN_USE, headerValue, HostListenError, isAllowedRequestHost, isLoopbackHost, pathnameIsLogged, redactRoutePath, rejectedResponse, sendRejected, } from "./http.js";
+import { bindListener as bind, EXIT_NON_LOOPBACK, headerValue, HostListenError, isAllowedRequestHost, isLoopbackHost, pathnameIsLogged, redactRoutePath, rejectedResponse, sendRejected, } from "./http.js";
 import { RUNTIME_VERSION } from "../version.js";
 export { adminKeyMatches } from "./http.js";
 export function createHost(options) {
@@ -25,7 +25,6 @@ export function createHost(options) {
     let closing = false;
     let closePromise;
     const adminStatusBody = async () => {
-        const tenants = await module.list();
         const aggregate = await module.summarize();
         return AdminStatusSchema.parse({
             service: "nylorun-runtime",
@@ -35,7 +34,7 @@ export function createHost(options) {
                 max: HOST_PROTOCOL.max,
                 features: [...HOST_PROTOCOL.features],
             },
-            tenants,
+            tenant: module.tenant(),
             aggregate,
             host: {
                 hostId: config.hostId,
@@ -45,7 +44,6 @@ export function createHost(options) {
         });
     };
     const adminApi = createAdminApi({
-        module,
         status: adminStatusBody,
         shutdown: () => void close(),
         document: adminDocument,
@@ -114,17 +112,7 @@ export function createHost(options) {
         };
     };
     /** Binds `listening`; once bound, a listener error is logged rather than lost. */
-    const bindListener = (listening, port, host) => new Promise((resolve, reject) => {
-        const failed = (error) => reject(error.code === "EADDRINUSE"
-            ? new HostListenError(`Port ${port} on ${host} is already in use`, EXIT_PORT_IN_USE, error)
-            : error);
-        listening.once("error", failed);
-        listening.listen(port, host, () => {
-            listening.off("error", failed);
-            listening.on("error", (error) => logger.error("listener_error", { error: error.message }));
-            resolve();
-        });
-    });
+    const bindListener = (listening, port, host) => bind(listening, port, host, (error) => logger.error("listener_error", { error: error.message }));
     async function listen() {
         if (server)
             throw new Error("Already listening");
@@ -159,6 +147,8 @@ export function createHost(options) {
                     : operator.port;
             adminUrl = `http://${operator.host}:${operatorPort}`;
         }
+        // The Tenant opens once the listener is bound: `/ready` and `/v1/admin/status` answer
+        // while it opens, and say why when it cannot.
         await module.start();
         logger.info("host_listening", {
             hostId: config.hostId,

package/dist/host/execution.d.ts

@@ -1,37 +1,39 @@
 /**
  * The Host's Durable Session Execution (architecture §6, §12.3, §14.8): one per process,
- * shared by every Tenant the Host opens.
+ * for the Tenant the Host serves.
  *
- * - `tenantExecution` is what the Host passes to each Tenant it opens
+ * - `tenantExecution` is what the Host passes to its Tenant when it opens it
  *   (`TenantOpenHooks.execution`): the execution, the `TenantWorkers` registry its handlers
- *   dispatch through (with `resolve` opening a Tenant on demand when an invocation arrives for
- *   one that is not open), and the Tenant status hook for stuck invocations.
- * - `start` serves the Worker endpoint for `--role worker|all` (`infra/workers.ts`) and does
- *   nothing for `api`, whose wakes, timers and sweep arming go through Restate's ingress.
- * - `armAll` re-arms every Tenant's sweep at startup. Arming is idempotent, so it is safe on
- *   every start, and it is what recovers from lost Restate state: the sweep re-wakes `runnable`
- *   sessions without a live owner (§14.8).
- * - `disarm` stops a deleted Tenant's sweep.
+ *   dispatch through (with `resolve` waiting for the Tenant when an invocation arrives while
+ *   it opens), and the Tenant status hook for stuck invocations.
+ * - `start` serves the Worker endpoint when the process runs loop (`infra/workers.ts`), and does
+ *   nothing for a core-only process, whose wakes, timers and sweep arming go through Restate's
+ *   ingress.
+ * - `armAll` arms the listed Tenants' sweeps (tests, recovery). Arming is idempotent; opening
+ *   the Tenant arms its own at every start, which is what recovers from lost Restate state:
+ *   the sweep re-wakes `runnable` sessions without a live owner (§14.8).
+ * - `disarm` stops a Tenant's sweep.
  *
- * **Order at startup.** Call `start` before opening any Tenant. Opening a Tenant arms its
+ * **Order at startup.** Call `start` before opening the Tenant. Opening the Tenant arms its
  * sweep through Restate's ingress, which answers 404 until a Worker has registered the
- * services, so the open would fail. An api-role process relies on a Worker having registered
+ * services, so the open would fail. A core-only process relies on a Worker having registered
  * them first.
  *
  * **One Worker URL.** `start` registers the Worker endpoint (`NYLORUN_WORKER_URL`) with
  * Restate once. Restate sends new invocations to the latest registered deployment, so
  * several Workers that each register their own URL do not share load: the last one to start
- * takes every new invocation. The V1 stack runs a single `runtime` container with
- * `--role all`. A deployment with several Worker processes (Helm, Cloud) must advertise one
+ * takes every new invocation. The local stack runs a single `runtime` container with
+ * `--service core,loop`. A deployment with several Worker processes (Helm, Cloud) must advertise one
  * load-balanced `NYLORUN_WORKER_URL` shared by all of them.
  */
 import type { DurableExecution } from "../execution/types.js";
 import type { Logger } from "../tenant/types.js";
 import { type TenantExecution, type TenantWorker } from "../tenant/worker.js";
-import type { RuntimeRole } from "./stack-config.js";
+import type { RuntimeServices } from "./stack-config.js";
 export interface CreateHostExecutionOptions {
     execution: DurableExecution;
-    role: RuntimeRole;
+    /** The services this process runs: it serves the Worker endpoint when they include loop. */
+    services: RuntimeServices;
     /** Finds or opens a Tenant an invocation arrived for that is not open on this process. */
     resolve: (tenantId: string) => Promise<TenantWorker | undefined>;
     logger?: Logger;
@@ -44,9 +46,9 @@ export interface CreateHostExecutionOptions {
     advanceGraceMs?: number;
 }
 export interface HostExecution {
-    /** Pass to every Tenant the Host opens (`TenantOpenHooks.execution`). */
+    /** Pass to the Tenant the Host opens (`TenantOpenHooks.execution`). */
     readonly tenantExecution: TenantExecution;
-    /** Serves the Worker endpoint for the worker and all roles. Idempotent. */
+    /** Serves the Worker endpoint when the process runs loop. Idempotent. */
     start(): Promise<void>;
     /** Stops serving: aborts running advances and waits for them. Idempotent. */
     stop(): Promise<void>;

package/dist/host/execution.js

@@ -3,7 +3,7 @@ import { TenantWorkers, } from "../tenant/worker.js";
 /** How many sweep arms `armAll` sends at once. */
 const ARM_CONCURRENCY = 16;
 export function createHostExecution(options) {
-    const { execution, role, logger } = options;
+    const { execution, services, logger } = options;
     const workers = new TenantWorkers({
         resolve: options.resolve,
         ...(options.advanceDeadlineMs !== undefined
@@ -27,7 +27,7 @@ export function createHostExecution(options) {
     return {
         tenantExecution,
         async start() {
-            started ??= startWorker({ role, execution, handlers: workers.handlers });
+            started ??= startWorker({ services, execution, handlers: workers.handlers });
             try {
                 await started;
             }

package/dist/host/gates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The gates service's process (blueprint §15, §19): one listener serving the Model Gate's and
+ * the Tool Gate's routes (`api/gate/routes.ts`), behind the same `Host` check as the Runtime's
+ * listeners.
+ * It opens no Tenant runtime, no Restate endpoint and no stream relay, and runs no migration;
+ * it needs only the Postgres pool and the Host's tenant directory (read-only).
+ *
+ * Nothing is written while a model call runs, so the server's request timeout sits above the
+ * gate's longest call. Closing stops accepting calls, lets running ones finish for up to
+ * `drainMs`, then aborts them (their providers' requests with them).
+ */
+import { type Server } from "node:http";
+import { type InflightCallsOptions } from "../gates/inflight.js";
+import type { openMcpServer } from "../mcp/connect.js";
+import type { OutboundPolicy } from "../tenant/outbound.js";
+import type { ModelCallSettings } from "../gates/model-gate.js";
+import { type TenantVaults } from "../gates/tenant-vaults.js";
+import type { PostgresClient } from "../store/postgres/connect.js";
+import type { Logger } from "../tenant/types.js";
+import type { GatesConfig } from "./stack-config.js";
+/** Above the gate's 600 s provider request timeout and the loop's 630 s client timeout. */
+export declare const GATES_REQUEST_TIMEOUT_MS = 660000;
+export interface StartGatesOptions {
+    readonly gates: GatesConfig;
+    readonly logger: Logger;
+    /** The Host root, for the Tenant's vault key. Required unless `vaults` is given. */
+    readonly hostRoot?: string;
+    /** The pool for the Tenant's vault and readiness. Required unless `vaults` is given. */
+    readonly database?: PostgresClient;
+    /** Replaces the Postgres-backed Tenant vault (tests). */
+    readonly vaults?: TenantVaults;
+    /** Retries and timeouts of model calls (tests). */
+    readonly settings?: ModelCallSettings;
+    /** Largest model call body (tests). */
+    readonly maxBodyBytes?: number;
+    /** How long `close` lets running calls finish. Default 10 s. */
+    readonly drainMs?: number;
+    /** How long keyed outcomes are kept, and how many (tests). */
+    readonly inflight?: InflightCallsOptions;
+    /** How the gate may call Action endpoints (`NYLORUN_ENDPOINT_*`). Default: no limits. */
+    readonly delivery?: OutboundPolicy;
+    /** How long an MCP connection may sit unused. Default `GATE_MCP_IDLE_MS`. */
+    readonly mcpIdleMs?: number;
+    /** Tests replace how a remote MCP server is opened. */
+    readonly openMcp?: typeof openMcpServer;
+    /**
+     * Serve the keys service too (`--service gates,keys`, F4.2): vault writes and token signing
+     * with the Tenant's vault key. The gateway is then not ready until the key file is there.
+     */
+    readonly keys?: boolean;
+}
+export interface GatesServer {
+    /** Where the gate listens, e.g. `http://0.0.0.0:4100`. */
+    readonly url: string;
+    readonly server: Server;
+    close(): Promise<void>;
+}
+export declare function startGates(options: StartGatesOptions): Promise<GatesServer>;

package/dist/host/gates.js

@@ -0,0 +1,127 @@
+/**
+ * The gates service's process (blueprint §15, §19): one listener serving the Model Gate's and
+ * the Tool Gate's routes (`api/gate/routes.ts`), behind the same `Host` check as the Runtime's
+ * listeners.
+ * It opens no Tenant runtime, no Restate endpoint and no stream relay, and runs no migration;
+ * it needs only the Postgres pool and the Host's tenant directory (read-only).
+ *
+ * Nothing is written while a model call runs, so the server's request timeout sits above the
+ * gate's longest call. Closing stops accepting calls, lets running ones finish for up to
+ * `drainMs`, then aborts them (their providers' requests with them).
+ */
+import { createServer } from "node:http";
+import { getRequestListener } from "@hono/node-server";
+import { createGatesApp } from "../api/gate/routes.js";
+import { createModelCallHandler } from "../gates/handler.js";
+import { createInflightCalls } from "../gates/inflight.js";
+import { createMcpHandler, GATE_MCP_IDLE_MS } from "../gates/mcp-handler.js";
+import { createToolCalls } from "../gates/tool-calls.js";
+import { existsSync } from "node:fs";
+import { tenantPaths } from "../tenant/paths.js";
+import { createTenantVaults } from "../gates/tenant-vaults.js";
+import { probeDatabase } from "../infra/database.js";
+import { bindListener, headerValue, isAllowedRequestHost, sendRejected } from "./http.js";
+/** Above the gate's 600 s provider request timeout and the loop's 630 s client timeout. */
+export const GATES_REQUEST_TIMEOUT_MS = 660_000;
+export async function startGates(options) {
+    const { gates, logger, database } = options;
+    let vaults = options.vaults;
+    if (!vaults) {
+        if (!database || options.hostRoot === undefined)
+            throw new Error("startGates needs the Postgres pool and the Host root");
+        vaults = createTenantVaults({ sql: database, hostRoot: options.hostRoot });
+    }
+    const inflight = createInflightCalls(options.inflight);
+    const mcpIdleMs = options.mcpIdleMs ?? GATE_MCP_IDLE_MS;
+    const mcp = createMcpHandler({
+        vaults,
+        logger,
+        idleMs: mcpIdleMs,
+        ...(options.openMcp ? { open: options.openMcp } : {}),
+    });
+    const toolCalls = createToolCalls({
+        vaults,
+        mcp,
+        logger,
+        ...(options.inflight ? { inflight: options.inflight } : {}),
+    });
+    const sweep = setInterval(() => void mcp.sweep(), Math.max(1_000, Math.min(mcpIdleMs, 60_000)));
+    sweep.unref();
+    const prune = setInterval(() => void toolCalls.prune(), 60 * 60_000);
+    prune.unref();
+    const app = createGatesApp({
+        token: gates.token,
+        inflight,
+        modelGate: createModelCallHandler({
+            vaults,
+            logger,
+            ...(options.settings ? { settings: options.settings } : {}),
+        }),
+        ready: async () => {
+            // The keys service needs the vault key, which `nylorun start` writes; it never creates one.
+            if (options.keys && options.hostRoot !== undefined && !existsSync(tenantPaths(options.hostRoot).kek))
+                return false;
+            if (!database)
+                return true;
+            try {
+                await probeDatabase(database, AbortSignal.timeout(2000));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        ...(options.maxBodyBytes !== undefined ? { maxBodyBytes: options.maxBodyBytes } : {}),
+        mcp,
+        toolCalls,
+        delivery: options.delivery ?? {},
+        logger,
+        ...(options.keys ? { keys: async () => (await vaults.open()).keys() } : {}),
+    });
+    const listener = getRequestListener(app.fetch);
+    const inFlight = new Set();
+    // The configured Host values, plus the loopback forms of the port actually bound (probes
+    // from inside the container; port 0 in tests).
+    let allowedHosts = gates.listen.allowedHosts;
+    const server = createServer((req, res) => {
+        if (!isAllowedRequestHost(headerValue(req, "host"), {
+            port: gates.listen.port,
+            host: gates.listen.host,
+            allowedHosts,
+        }))
+            return sendRejected(res, 421, "host_rejected", "Host header is not an allowed address of the gateway");
+        inFlight.add(res);
+        res.once("close", () => inFlight.delete(res));
+        void listener(req, res);
+    });
+    server.requestTimeout = GATES_REQUEST_TIMEOUT_MS;
+    await bindListener(server, gates.listen.port, gates.listen.host, (error) => logger.error("listener_error", { error: error.message }));
+    const port = server.address().port;
+    allowedHosts = [
+        ...new Set([...allowedHosts, `localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`]),
+    ];
+    const url = `http://${gates.listen.host.includes(":") ? `[${gates.listen.host}]` : gates.listen.host}:${port}`;
+    let closing;
+    return {
+        url,
+        server,
+        close() {
+            closing ??= (async () => {
+                const closed = new Promise((resolve) => server.close(() => resolve()));
+                server.closeIdleConnections();
+                const deadline = Date.now() + (options.drainMs ?? 10_000);
+                while (inFlight.size > 0 && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+                // Closing a running call's connection aborts an unkeyed one; keyed calls stop here.
+                server.closeAllConnections();
+                inflight.close();
+                toolCalls.close();
+                clearInterval(sweep);
+                clearInterval(prune);
+                await mcp.closeAll();
+                await closed;
+            })();
+            return closing;
+        },
+    };
+}

package/dist/host/http.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage, ServerResponse } from "node:http";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
 import { jsonResponse } from "../api/http/respond.js";
 import { type ErrorCode, type ProtocolRange } from "@nylorun/core/compatibility";
 export declare const OPAQUE_NOT_FOUND: {
@@ -13,6 +13,11 @@ export declare class HostListenError extends Error {
     readonly cause?: unknown;
     constructor(message: string, exitCode: number, cause?: unknown);
 }
+/**
+ * Binds `listening` on `host:port`. A port in use rejects with `HostListenError` (exit 98);
+ * once bound, a listener error goes to `onError` rather than being lost.
+ */
+export declare function bindListener(listening: Server, port: number, host: string, onError: (error: Error) => void): Promise<void>;
 export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
 /** `sendJson` as a Response, byte for byte (with any extra headers): the Host's answers. */
 export { jsonResponse };

package/dist/host/http.js

@@ -18,6 +18,23 @@ export class HostListenError extends Error {
         this.name = "HostListenError";
     }
 }
+/**
+ * Binds `listening` on `host:port`. A port in use rejects with `HostListenError` (exit 98);
+ * once bound, a listener error goes to `onError` rather than being lost.
+ */
+export function bindListener(listening, port, host, onError) {
+    return new Promise((resolve, reject) => {
+        const failed = (error) => reject(error.code === "EADDRINUSE"
+            ? new HostListenError(`Port ${port} on ${host} is already in use`, EXIT_PORT_IN_USE, error)
+            : error);
+        listening.once("error", failed);
+        listening.listen(port, host, () => {
+            listening.off("error", failed);
+            listening.on("error", onError);
+            resolve();
+        });
+    });
+}
 export function sendJson(response, status, body) {
     const payload = JSON.stringify(body);
     // No Access-Control-* headers (D§11).

package/dist/host/index.d.ts

@@ -4,5 +4,5 @@ export { createHost, adminKeyMatches, type CreateHostOptions, type HostServer }
 export { createHostLogger } from "./logger.js";
 export { configForFactory } from "./config-for.js";
 export { createHostExecution, type CreateHostExecutionOptions, type HostExecution, } from "./execution.js";
-export { parseStackConfig, StackConfigError, type ContainerListen, type RuntimeRole, type StackConfig, type StackEndpoints, } from "./stack-config.js";
+export { parseStackConfig, StackConfigError, type ContainerListen, type RuntimeRole, type RuntimeService, type RuntimeServices, type StackConfig, type StackEndpoints, } from "./stack-config.js";
 export { EXIT_PORT_IN_USE, EXIT_NON_LOOPBACK, HostListenError, OPAQUE_NOT_FOUND, } from "./http.js";