@skilder-ai/runtime 0.9.24 → 0.9.25

package/README.md

@@ -45,7 +45,9 @@ When `REMOTE_PORT` is set, the runtime exposes `GET /health`:
 - **`200 { status: 'ok' }`** — NATS connected, an active round-trip probe (`flush`, 2s timeout) succeeded, and the runtime is authenticated
 - **`503 { status: 'error', message: '...' }`** — NATS disconnected, NATS unreachable (flush timed out), not authenticated, or an unexpected error occurred
 
-> **Note:** The health endpoint is only available when `REMOTE_PORT` is set. CLI/standalone mode (no `REMOTE_PORT`) does not start an HTTP server — this is intentional.
+Health is independent of the remote MCP endpoints: a runtime that serves no MCP endpoint (no `MCP_REMOTE_ENABLED`) is still healthcheckable. The container image defaults `REMOTE_PORT` to `3001`, so every runtime container has a working healthcheck out of the box.
+
+> **Note:** `npx`-installed runtimes bind no port unless you set `REMOTE_PORT` yourself, and stdio mode (`USER_KEY`) never starts an HTTP server — it is spawned per client, so a shared port would collide.
 
 ### Docker Compose setup
 
@@ -54,7 +56,8 @@ services:
   runtime:
     image: your-runtime-image
     environment:
-      REMOTE_PORT: "3001"
+      REMOTE_PORT: "3001"          # web service (health); the image defaults this
+      MCP_REMOTE_ENABLED: "true"   # also serve the remote MCP endpoints on it
       RUNTIME_KEY: "<RUNTIME_API_KEY>"
       NATS_SERVERS: "nats:4222"
     healthcheck:

package/dist/index.js

@@ -87816,6 +87816,23 @@ function parsePositiveIntEnv(name21, fallback) {
   }
   return parsed;
 }
+function parseOptionalPositiveIntEnv(name21) {
+  const raw = process.env[name21];
+  if (raw === void 0 || raw === "") return void 0;
+  return parsePositiveIntEnv(name21, 0);
+}
+var TRUE_VALUES = ["true", "1", "yes", "on"];
+var FALSE_VALUES = ["false", "0", "no", "off"];
+function parseBooleanEnv(name21, fallback) {
+  const raw = process.env[name21];
+  if (raw === void 0 || raw === "") return fallback;
+  const normalized = raw.trim().toLowerCase();
+  if (TRUE_VALUES.includes(normalized)) return true;
+  if (FALSE_VALUES.includes(normalized)) return false;
+  throw new Error(
+    `Invalid ${name21}: "${raw}". Must be one of ${[...TRUE_VALUES, ...FALSE_VALUES].join(", ")}.`
+  );
+}
 
 // ../common/src/constants.node.ts
 var MCP_TOOL_EXECUTION_TIMEOUT = parseInt(process.env.MCP_TOOL_EXECUTION_TIMEOUT ?? "60000", 10);
@@ -152767,6 +152784,16 @@ McpStdioService = __decorate15([
 // src/services/fastify.manager.service.ts
 var import_fastify = __toESM(require_fastify());
 var import_cors = __toESM(require_cors());
+
+// src/config/server.ts
+function remotePort() {
+  return parseOptionalPositiveIntEnv("REMOTE_PORT");
+}
+function mcpRemoteEnabled() {
+  return parseBooleanEnv("MCP_REMOTE_ENABLED", false);
+}
+
+// src/services/fastify.manager.service.ts
 var __decorate16 = function(decorators, target, key, desc) {
   var c3 = arguments.length, r2 = c3 < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d2;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r2 = Reflect.decorate(decorators, target, key, desc);
@@ -152796,14 +152823,14 @@ var FastifyManagerService = class FastifyManagerService2 extends LifecycleServic
     this.logger = this.loggerService.getLogger(this.name);
   }
   async initialize() {
-    const remotePort = process.env.REMOTE_PORT;
-    if (!remotePort) {
+    const port = remotePort();
+    if (!port) {
       this.logger.warn("REMOTE_PORT is not set, Fastify manager will not start");
       return;
     }
     this.logger.info("Starting Fastify manager service");
     await this.setupFastifyInstance();
-    this.port = parseInt(remotePort);
+    this.port = port;
   }
   /**
    * Start listening on the configured port.
@@ -152825,6 +152852,10 @@ var FastifyManagerService = class FastifyManagerService2 extends LifecycleServic
       this.isListening = true;
       this.logger.info(`Fastify server listening on port ${this.port}`);
     } catch (error48) {
+      if (error48?.code === "EADDRINUSE") {
+        this.logger.error({ event: "fastify_listen_failed", reason: "port_in_use", port: this.port }, `Port ${this.port} is already in use. Set REMOTE_PORT to a free port, or unset it to run without a web service.`);
+        throw error48;
+      }
       this.logger.error(`Failed to start Fastify server: ${error48}`);
       throw error48;
     }
@@ -152835,6 +152866,7 @@ var FastifyManagerService = class FastifyManagerService2 extends LifecycleServic
       await this.fastifyInstance.close();
       this.fastifyInstance = void 0;
     }
+    this.isListening = false;
   }
   /**
    * Returns the shared Fastify instance for route registration
@@ -162087,7 +162119,8 @@ function validateAndDetectMode() {
   const userKey = process.env.USER_KEY;
   const runtimeKey = process.env.RUNTIME_KEY;
   const runtimeName = process.env.RUNTIME_NAME;
-  const remotePort = process.env.REMOTE_PORT;
+  const mcpRemote = mcpRemoteEnabled();
+  const port = userKey ? void 0 : remotePort();
   const keyVariables = [systemKey, userKey, runtimeKey];
   const keyVariablesSet = keyVariables.filter((key) => !!key);
   if (keyVariablesSet.length > 1) {
@@ -162100,26 +162133,32 @@ function validateAndDetectMode() {
       throw new Error("Invalid configuration: SYSTEM_KEY requires RUNTIME_NAME");
     }
   }
-  if (remotePort && userKey) {
+  if (mcpRemote && userKey) {
     throw new Error(
-      "Invalid configuration: REMOTE_PORT is mutually exclusive with USER_KEY. Please use only REMOTE_PORT for edge runtimes"
+      "Invalid configuration: MCP_REMOTE_ENABLED is mutually exclusive with USER_KEY. USER_KEY serves MCP over stdio; use RUNTIME_KEY or RUNTIME_NAME for remote MCP."
     );
   }
+  if (mcpRemote && !port) {
+    throw new Error("Invalid configuration: MCP_REMOTE_ENABLED requires REMOTE_PORT, which is where the MCP endpoints are served.");
+  }
   if ((runtimeName || runtimeKey) && userKey) {
     throw new Error("Invalid configuration: trying to start both a runtime and a user, this is not supported");
   }
+  if (userKey && process.env.REMOTE_PORT) {
+    console.warn("REMOTE_PORT is ignored in stdio mode (USER_KEY): stdio runtimes do not start a web service");
+  }
   if (userKey) {
     return "MCP_STDIO";
   } else if (runtimeName || runtimeKey) {
-    if (remotePort) {
+    if (mcpRemote) {
       return "EDGE_MCP_STREAM";
     }
     return "EDGE";
-  } else if (remotePort) {
+  } else if (mcpRemote) {
     return "STANDALONE_MCP_STREAM";
   } else {
     throw new Error(
-      "Invalid configuration: At least one of USER_KEY, RUNTIME_NAME, RUNTIME_KEY, or REMOTE_PORT must be set. See documentation for valid operational modes."
+      "Invalid configuration: At least one of USER_KEY, RUNTIME_NAME, RUNTIME_KEY, or MCP_REMOTE_ENABLED must be set. See documentation for valid operational modes."
     );
   }
 }
@@ -162129,19 +162168,22 @@ var start = () => {
   const runtimeExecutionId = (0, import_crypto3.randomBytes)(16).toString("hex");
   container.bind(RUNTIME_EXECUTION_ID).toConstantValue(runtimeExecutionId);
   container.bind(AuthService).toSelf().inSingletonScope();
+  const webService = mode !== "MCP_STDIO" && remotePort() !== void 0;
+  if (webService) {
+    container.bind(FastifyManagerService).toSelf().inSingletonScope();
+  } else {
+    container.bind(FastifyManagerService).toConstantValue(void 0);
+  }
   if (mode === "MCP_STDIO") {
     container.bind(McpStdioService).toSelf().inSingletonScope();
-    container.bind(FastifyManagerService).toConstantValue(void 0);
     container.bind(McpSseService).toConstantValue(void 0);
     container.bind(McpStreamableService).toConstantValue(void 0);
   } else if (mode === "EDGE_MCP_STREAM" || mode === "STANDALONE_MCP_STREAM") {
-    container.bind(FastifyManagerService).toSelf().inSingletonScope();
     container.bind(McpSseService).toSelf().inSingletonScope();
     container.bind(McpStreamableService).toSelf().inSingletonScope();
     container.bind(McpStdioService).toConstantValue(void 0);
   } else {
     container.bind(McpStdioService).toConstantValue(void 0);
-    container.bind(FastifyManagerService).toConstantValue(void 0);
     container.bind(McpSseService).toConstantValue(void 0);
     container.bind(McpStreamableService).toConstantValue(void 0);
   }