stageflow 0.23.0 → 0.27.0

package/dist/server/controlToken.js

@@ -0,0 +1,241 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { isLoopbackHostname } from "./allowedHosts.js";
+const CONTROL_TOKEN_PREFIX = "STAGEFLOW_CONTROL_TOKEN_";
+const DEFAULT_CALLER_ID = "default";
+function digest(value) {
+    return createHash("sha256").update(value).digest();
+}
+function validateToken(token, label) {
+    if (!token || /\s/.test(token) || token.length < 32) {
+        throw new Error(`${label} requires a token of at least 32 characters with no whitespace`);
+    }
+    return token;
+}
+function normalizeCallerId(name) {
+    return name.toLowerCase();
+}
+/** Parse named drive callers from STAGEFLOW_CONTROL_TOKEN_<NAME> / _FILE. */
+export function listNamedControlTokenEnvKeys(env = process.env) {
+    const out = [];
+    const seen = new Set();
+    for (const key of Object.keys(env)) {
+        if (!key.startsWith(CONTROL_TOKEN_PREFIX))
+            continue;
+        let namePart;
+        let isFile = false;
+        if (key.endsWith("_FILE")) {
+            namePart = key.slice(CONTROL_TOKEN_PREFIX.length, -"_FILE".length);
+            isFile = true;
+        }
+        else {
+            namePart = key.slice(CONTROL_TOKEN_PREFIX.length);
+        }
+        if (namePart === "" || namePart === "FILE")
+            continue;
+        const caller_id = normalizeCallerId(namePart);
+        const dedupe = `${caller_id}:${isFile ? "file" : "plain"}`;
+        if (seen.has(dedupe))
+            continue;
+        seen.add(dedupe);
+        out.push({ envKey: key, caller_id, isFile });
+    }
+    return out;
+}
+function assertUniqueDigests(entries) {
+    const byHex = new Map();
+    for (const entry of entries) {
+        const hex = entry.digest.toString("hex");
+        const prior = byHex.get(hex);
+        if (prior !== undefined) {
+            throw new Error(`Duplicate control token digests for ${prior} and ${entry.label}`);
+        }
+        byHex.set(hex, entry.label);
+    }
+}
+export function loadControlTokens(env = process.env) {
+    const driveRaw = readSecretFromEnvOrFile(env, "STAGEFLOW_CONTROL_TOKEN");
+    const readRaw = readSecretFromEnvOrFile(env, "STAGEFLOW_READ_TOKEN");
+    const callerBases = new Map();
+    for (const named of listNamedControlTokenEnvKeys(env)) {
+        const base = named.isFile
+            ? named.envKey.slice(0, -"_FILE".length)
+            : named.envKey;
+        if (!callerBases.has(named.caller_id)) {
+            callerBases.set(named.caller_id, base);
+        }
+    }
+    const namedDrive = [];
+    for (const [caller_id, base] of callerBases) {
+        const raw = readSecretFromEnvOrFile(env, base);
+        if (raw === undefined)
+            continue;
+        namedDrive.push({
+            caller_id,
+            digest: digest(validateToken(raw, base)),
+        });
+    }
+    const driveDigest = driveRaw
+        ? digest(validateToken(driveRaw, "STAGEFLOW_CONTROL_TOKEN"))
+        : undefined;
+    const readDigest = readRaw
+        ? digest(validateToken(readRaw, "STAGEFLOW_READ_TOKEN"))
+        : undefined;
+    const uniqueness = [];
+    if (driveDigest) {
+        uniqueness.push({ label: "STAGEFLOW_CONTROL_TOKEN", digest: driveDigest });
+    }
+    if (readDigest) {
+        uniqueness.push({ label: "STAGEFLOW_READ_TOKEN", digest: readDigest });
+    }
+    for (const named of namedDrive) {
+        uniqueness.push({
+            label: `STAGEFLOW_CONTROL_TOKEN_${named.caller_id}`,
+            digest: named.digest,
+        });
+    }
+    assertUniqueDigests(uniqueness);
+    return { driveDigest, readDigest, namedDrive };
+}
+/** Plain bearer for CLI→host calls. Drive preferred; read only for GET/HEAD. */
+export function resolveClientBearerToken(method, env = process.env) {
+    const driveRaw = readSecretFromEnvOrFile(env, "STAGEFLOW_CONTROL_TOKEN");
+    if (driveRaw !== undefined) {
+        return validateToken(driveRaw, "STAGEFLOW_CONTROL_TOKEN");
+    }
+    if (method === "GET" || method === "HEAD") {
+        const readRaw = readSecretFromEnvOrFile(env, "STAGEFLOW_READ_TOKEN");
+        if (readRaw !== undefined) {
+            return validateToken(readRaw, "STAGEFLOW_READ_TOKEN");
+        }
+    }
+    return undefined;
+}
+export function clientAuthorizationHeaders(method, env = process.env) {
+    const token = resolveClientBearerToken(method, env);
+    if (token === undefined)
+        return {};
+    return { Authorization: `Bearer ${token}` };
+}
+export function hasDriveToken(tokens) {
+    return tokens.driveDigest !== undefined || tokens.namedDrive.length > 0;
+}
+export function hasAnyToken(tokens) {
+    return (tokens.driveDigest !== undefined ||
+        tokens.readDigest !== undefined ||
+        tokens.namedDrive.length > 0);
+}
+export function isLoopbackBind(bind) {
+    const normalized = bind.startsWith("[") && bind.endsWith("]")
+        ? bind.slice(1, -1)
+        : bind;
+    return isLoopbackHostname(normalized);
+}
+export function refuseBindMessage(bind) {
+    return `Refusing to start: Stageflow is configured to bind ${bind}, which is reachable from outside this
+machine, but no control token is set.
+
+Anyone who can reach this port could start a pipeline run, and pipeline stages execute arbitrary
+shell commands with this process's environment — including provider API keys.
+
+Set one of:
+  STAGEFLOW_CONTROL_TOKEN=<at least 32 characters>
+  STAGEFLOW_CONTROL_TOKEN_FILE=/path/to/secret
+  STAGEFLOW_CONTROL_TOKEN_<NAME>=<at least 32 characters>
+
+Or bind to loopback instead:
+  --host 127.0.0.1   (or unset STAGEFLOW_BIND)`;
+}
+export function assertBindAllowed(bind, tokens) {
+    if (!isLoopbackBind(bind) && !hasDriveToken(tokens)) {
+        throw new BindRefusedError(refuseBindMessage(bind));
+    }
+}
+export class BindRefusedError extends Error {
+    exitCode = 1;
+    constructor(message) {
+        super(message);
+        this.name = "BindRefusedError";
+    }
+}
+export function requiredScopeFor(method, pathname) {
+    if (pathname === "/mcp")
+        return "drive";
+    if (!pathname.startsWith("/api/"))
+        return null;
+    if (pathname === "/api/backup" || pathname.startsWith("/api/backup/")) {
+        return "drive";
+    }
+    if (method === "GET" || method === "HEAD")
+        return "read";
+    return "drive";
+}
+/**
+ * Digest once; timingSafeEqual against every loaded digest (no early-return oracle).
+ * Named control tokens are drive-only; READ stays the singular global token.
+ */
+export function authenticateBearer(tokens, authorization) {
+    const match = authorization?.match(/^Bearer ([^\s]+)$/i);
+    if (!match)
+        return undefined;
+    const hash = digest(match[1]);
+    const candidates = [];
+    if (tokens.driveDigest) {
+        candidates.push({
+            scope: "drive",
+            caller_id: DEFAULT_CALLER_ID,
+            digest: tokens.driveDigest,
+        });
+    }
+    if (tokens.readDigest) {
+        candidates.push({
+            scope: "read",
+            caller_id: DEFAULT_CALLER_ID,
+            digest: tokens.readDigest,
+        });
+    }
+    for (const named of tokens.namedDrive) {
+        candidates.push({
+            scope: "drive",
+            caller_id: named.caller_id,
+            digest: named.digest,
+        });
+    }
+    let matched;
+    for (const candidate of candidates) {
+        if (timingSafeEqual(candidate.digest, hash)) {
+            matched = { scope: candidate.scope, caller_id: candidate.caller_id };
+        }
+    }
+    return matched;
+}
+function scopeSatisfies(granted, required) {
+    if (required === "read")
+        return granted === "read" || granted === "drive";
+    return granted === "drive";
+}
+export function enforceBearerAuth(tokens, req, res, required) {
+    if (!hasAnyToken(tokens))
+        return { ok: true, auth: undefined };
+    const granted = authenticateBearer(tokens, req.headers.authorization);
+    if (granted === undefined) {
+        const payload = JSON.stringify({ error: "Unauthorized" });
+        res.writeHead(401, {
+            "Content-Type": "application/json; charset=utf-8",
+            "Content-Length": Buffer.byteLength(payload),
+            "WWW-Authenticate": "Bearer",
+        });
+        res.end(payload);
+        return { ok: false };
+    }
+    if (!scopeSatisfies(granted.scope, required)) {
+        const payload = JSON.stringify({ error: "Forbidden" });
+        res.writeHead(403, {
+            "Content-Type": "application/json; charset=utf-8",
+            "Content-Length": Buffer.byteLength(payload),
+        });
+        res.end(payload);
+        return { ok: false };
+    }
+    return { ok: true, auth: granted };
+}

package/dist/server/createHttpHost.d.ts

@@ -3,7 +3,11 @@ import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
 import type { StageflowHostBootstrap } from "./bootstrap.js";
+import { type AllowedHosts } from "./allowedHosts.js";
+import { requiredScopeFor, type ControlTokens } from "./controlToken.js";
 export declare const DEFAULT_PORT = 3847;
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+export declare const DEFAULT_MAX_CONNECTIONS = 256;
 export declare function json(res: ServerResponse, status: number, body: unknown): void;
 export type HttpHostRouteContext = {
     req: IncomingMessage;
@@ -19,6 +23,10 @@ export type CreateHttpHostOptions = {
     host: string;
     port: number;
     routes: (ctx: HttpHostRouteContext) => Promise<boolean | void>;
+    allowedHosts?: AllowedHosts;
+    controlTokens?: ControlTokens;
+    requestTimeoutMs?: number;
+    maxConnections?: number;
 };
 export type HttpHostEnvelope = {
     server: Server;
@@ -26,9 +34,10 @@ export type HttpHostEnvelope = {
     host: string;
     url: string;
     mcpUrl: string;
-    manager: RunManager;
-    store: RunStore;
+    manager?: RunManager;
+    store?: RunStore;
     runChangeBus: RunChangeBus;
     mcpStateless: boolean;
 };
 export declare function createHttpHost(options: CreateHttpHostOptions): Promise<HttpHostEnvelope>;
+export { requiredScopeFor };

package/dist/server/createHttpHost.js

@@ -1,6 +1,14 @@
 import { createServer, } from "node:http";
-import { localhostHostValidation, localhostOriginValidation, } from "@modelcontextprotocol/node";
+import { logger as rootLogger } from "../logging/logger.js";
+import { assertAllowedHttpAccess, resolveAllowedHosts, } from "./allowedHosts.js";
+import { enforceBearerAuth, loadControlTokens, requiredScopeFor, } from "./controlToken.js";
+import { requestAuthFromBearer, runWithRequestAuth, } from "./requestAuthContext.js";
+import { advertisedHost } from "./listenHost.js";
+import { handleLivez, handleReadyz } from "./healthSurfaces.js";
 export const DEFAULT_PORT = 3847;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export const DEFAULT_MAX_CONNECTIONS = 256;
+const log = rootLogger.child({ component: "http" });
 export function json(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
@@ -9,25 +17,101 @@ export function json(res, status, body) {
     });
     res.end(payload);
 }
+function resolveRequestTimeoutMs(env = process.env) {
+    const raw = env.STAGEFLOW_REQUEST_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_REQUEST_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_REQUEST_TIMEOUT_MS;
+    return n;
+}
+function resolveMaxConnections(env = process.env) {
+    const raw = env.STAGEFLOW_MAX_CONNECTIONS;
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_MAX_CONNECTIONS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_MAX_CONNECTIONS;
+    return Math.floor(n);
+}
 export async function createHttpHost(options) {
     const { boot, host, port, routes } = options;
-    const validateMcpHost = localhostHostValidation();
-    const validateMcpOrigin = localhostOriginValidation();
+    const allowedHosts = options.allowedHosts ?? resolveAllowedHosts();
+    const controlTokens = options.controlTokens ?? loadControlTokens();
+    const requestTimeoutMs = options.requestTimeoutMs ?? resolveRequestTimeoutMs();
+    const maxConnections = options.maxConnections ?? resolveMaxConnections();
     const server = createServer(async (req, res) => {
         const method = req.method ?? "GET";
-        const url = new URL(req.url ?? "/", `http://${host}:${port}`);
+        const url = new URL(req.url ?? "/", `http://${advertisedHost(host)}:${port}`);
         const pathname = url.pathname;
+        if ((pathname === "/livez" || pathname === "/readyz") &&
+            (method === "GET" || method === "HEAD")) {
+            if (!assertAllowedHttpAccess(allowedHosts, req, res))
+                return;
+            if (pathname === "/livez") {
+                handleLivez(req, res);
+                return;
+            }
+            await handleReadyz(req, res, boot);
+            return;
+        }
+        if (pathname === "/api/a2a/status" && method === "GET") {
+            if (!assertAllowedHttpAccess(allowedHosts, req, res))
+                return;
+            if (boot.serveBlocked !== undefined) {
+                json(res, 503, {
+                    error: boot.serveBlocked.reason,
+                    code: boot.serveBlocked.code,
+                });
+                return;
+            }
+            const a2aAuth = enforceBearerAuth(controlTokens, req, res, "read");
+            if (!a2aAuth.ok)
+                return;
+            json(res, 200, boot.a2a?.status ?? { state: "disabled" });
+            return;
+        }
+        if (boot.serveBlocked !== undefined) {
+            const a2aOwned = pathname === "/a2a" ||
+                pathname === "/.well-known/agent-card.json" ||
+                pathname.startsWith("/a2a/contracts/") ||
+                pathname.startsWith("/a2a/artifacts/");
+            if (a2aOwned) {
+                if (!assertAllowedHttpAccess(allowedHosts, req, res))
+                    return;
+                json(res, 503, {
+                    error: boot.serveBlocked.reason,
+                    code: boot.serveBlocked.code,
+                });
+                return;
+            }
+        }
+        if (await boot.a2a?.handle(req, res, pathname))
+            return;
         if (pathname === "/mcp") {
-            if (!validateMcpHost(req, res) || !validateMcpOrigin(req, res)) {
+            if (!assertAllowedHttpAccess(allowedHosts, req, res))
+                return;
+            if (boot.serveBlocked !== undefined) {
+                json(res, 503, {
+                    error: boot.serveBlocked.reason,
+                    code: boot.serveBlocked.code,
+                });
                 return;
             }
+            const mcpAuth = enforceBearerAuth(controlTokens, req, res, "drive");
+            if (!mcpAuth.ok)
+                return;
+            res.setTimeout(0);
             try {
-                await boot.mcpHandler.handle(req, res);
+                await runWithRequestAuth(requestAuthFromBearer(mcpAuth.auth, "mcp"), () => boot.mcpHandler.handle(req, res));
             }
             catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                log.error("mcp.handler_error", message);
                 if (!res.headersSent) {
                     res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
-                    res.end(err instanceof Error ? err.message : String(err));
+                    res.end(message);
                 }
             }
             return;
@@ -45,26 +129,41 @@ export async function createHttpHost(options) {
             return;
         json(res, 404, { error: "Not found" });
     });
-    server.requestTimeout = 0;
+    // requestTimeout bounds receiving the request body (408); idle socket timeout
+    // stays 0 so MCP SSE can outlive requestTimeout.
+    server.requestTimeout = requestTimeoutMs;
+    server.maxConnections = maxConnections;
     server.on("close", () => {
+        boot.stopGcInterval();
         void boot.mcpHandler.close();
     });
     await new Promise((resolve, reject) => {
         server.listen(port, host, () => resolve());
         server.on("error", reject);
     });
+    server.on("error", (err) => {
+        log.error("host.server_error", err instanceof Error ? err.message : String(err));
+    });
     const address = server.address();
     const boundPort = address && typeof address !== "string" ? address.port : port;
-    const url = `http://${host}:${boundPort}`;
+    const publicHost = advertisedHost(host);
+    const url = `http://${publicHost}:${boundPort}`;
+    const mcpUrl = `${url}/mcp`;
+    log.info("host.listening", `listening on ${url}`, {
+        host,
+        port: boundPort,
+        mcp_url: mcpUrl,
+    });
     return {
         server,
         port: boundPort,
         host,
         url,
-        mcpUrl: `${url}/mcp`,
+        mcpUrl,
         manager: boot.manager,
         store: boot.store,
         runChangeBus: boot.runChangeBus,
         mcpStateless: boot.mcpStateless,
     };
 }
+export { requiredScopeFor };

package/dist/server/ensureGlobalService.d.ts

@@ -11,12 +11,15 @@ export type ServiceProbeResult = "up" | "unreachable" | "unhealthy";
 export declare function hostBaseUrl(): string;
 export declare function probeGlobalServiceDetailed(): Promise<ServiceProbeResult>;
 export declare function defaultProbeHost(): Promise<HostProbeResult>;
+export declare const STAGEFLOW_NO_AUTOSTART = "STAGEFLOW_NO_AUTOSTART";
+/** Truthy when set and not empty / `0` / `false` (case-insensitive). */
+export declare function isNoAutostartEnabled(env?: NodeJS.ProcessEnv): boolean;
 export type EnsureGlobalServiceResult = {
     ok: true;
     alreadyRunning: boolean;
 } | {
     ok: false;
-    reason: "port_occupied" | "spawn_failed" | "timed_out";
+    reason: "port_occupied" | "spawn_failed" | "timed_out" | "autostart_disabled" | "bind_refused";
     message: string;
 };
 export interface EnsureGlobalServiceOptions {
@@ -26,6 +29,7 @@ export interface EnsureGlobalServiceOptions {
     spawnFn?: (command: string, args: string[], options: Parameters<typeof spawnDefault>[2]) => ChildProcess;
     pollIntervalMs?: number;
     timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Health-probe-then-spawn: makes sure a global Stageflow service is

package/dist/server/ensureGlobalService.js

@@ -3,7 +3,9 @@ import { openSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensureGlobalHome } from "../project/globalHome.js";
+import { assertBindAllowed, BindRefusedError, loadControlTokens, } from "./controlToken.js";
 import { DEFAULT_PORT } from "./createHttpHost.js";
+import { resolveListenHost } from "./listenHost.js";
 /**
  * The well-known port the global service listens on. Overridable via
  * STAGEFLOW_SERVICE_PORT — real usage never sets this (there's exactly one
@@ -46,7 +48,7 @@ export async function probeGlobalServiceDetailed() {
     try {
         let res;
         try {
-            res = await fetch(`${hostBaseUrl()}/api/health`, { signal: ac.signal });
+            res = await fetch(`${hostBaseUrl()}/livez`, { signal: ac.signal });
         }
         catch {
             return "unreachable";
@@ -70,6 +72,15 @@ export async function defaultProbeHost() {
 }
 const DEFAULT_POLL_INTERVAL_MS = 200;
 const DEFAULT_TIMEOUT_MS = Number(process.env.STAGEFLOW_AUTOSTART_TIMEOUT_MS) || 10_000;
+export const STAGEFLOW_NO_AUTOSTART = "STAGEFLOW_NO_AUTOSTART";
+/** Truthy when set and not empty / `0` / `false` (case-insensitive). */
+export function isNoAutostartEnabled(env = process.env) {
+    const raw = env[STAGEFLOW_NO_AUTOSTART];
+    if (raw === undefined || raw.trim() === "")
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized !== "0" && normalized !== "false";
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -83,6 +94,7 @@ export async function ensureGlobalService(options = {}) {
     const spawnFn = options.spawnFn ?? spawnDefault;
     const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const env = options.env ?? process.env;
     const initial = await probeHost();
     if (initial === "up") {
         return { ok: true, alreadyRunning: true };
@@ -94,6 +106,28 @@ export async function ensureGlobalService(options = {}) {
             message: `Port ${resolveServicePort()} is already in use by a process that isn't the Stageflow service (its health check didn't return valid health JSON). Free the port and try again.`,
         };
     }
+    if (isNoAutostartEnabled(env)) {
+        const url = hostBaseUrl();
+        return {
+            ok: false,
+            reason: "autostart_disabled",
+            message: `No Stageflow Host is answering at ${url}. Autostart is disabled (STAGEFLOW_NO_AUTOSTART). Start the Host with \`sf mcp\`, or in Docker check that the container's entrypoint is running.`,
+        };
+    }
+    try {
+        const bind = resolveListenHost({ env });
+        assertBindAllowed(bind, loadControlTokens(env));
+    }
+    catch (err) {
+        if (err instanceof BindRefusedError) {
+            return {
+                ok: false,
+                reason: "bind_refused",
+                message: err.message,
+            };
+        }
+        throw err;
+    }
     const cliEntry = options.cliEntry ?? process.argv[1] ?? "";
     const globalHome = ensureGlobalHome();
     const logPath = path.join(globalHome, "service.log");

package/dist/server/healthSurfaces.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { StageflowHostBootstrap } from "./bootstrap.js";
+export declare function handleLivez(_req: IncomingMessage, res: ServerResponse): void;
+export declare function handleReadyz(_req: IncomingMessage, res: ServerResponse, boot: StageflowHostBootstrap): Promise<void>;
+export declare function buildRichHealthPayload(boot: StageflowHostBootstrap): Promise<Record<string, unknown>>;
+export declare function handleApiHealth(_req: IncomingMessage, res: ServerResponse, boot: StageflowHostBootstrap): Promise<void>;

package/dist/server/healthSurfaces.js

@@ -0,0 +1,98 @@
+import { PACKAGE_VERSION, BUILD_SHA } from "../package-meta.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { redactHostConfig } from "../config/hostConfig.js";
+import { resolveCatalogRoots } from "../config/resolveCatalogRoots.js";
+import { json } from "./createHttpHost.js";
+import { livezBody, probeGitVersion, readSchemaHealth, runReadyzChecks, } from "../diagnostics/checks.js";
+import { buildEgressHealth } from "../net/proxy.js";
+import { toolchainHealthMap } from "../preflight/toolchain.js";
+export function handleLivez(_req, res) {
+    json(res, 200, livezBody());
+}
+export async function handleReadyz(_req, res, boot) {
+    if (boot.serveBlocked !== undefined) {
+        json(res, 503, {
+            ready: false,
+            code: boot.serveBlocked.code,
+            error: boot.serveBlocked.reason,
+            checks: {
+                store_openable: false,
+                home_writable: false,
+                migrations_complete: false,
+                git_present: false,
+            },
+        });
+        return;
+    }
+    if (boot.store === undefined) {
+        json(res, 503, {
+            ready: false,
+            error: "store unavailable",
+            checks: {
+                store_openable: false,
+                home_writable: false,
+                migrations_complete: false,
+                git_present: false,
+            },
+        });
+        return;
+    }
+    const result = await runReadyzChecks({
+        store: boot.store,
+        homeDir: globalStageflowHome(),
+    });
+    json(res, result.ready ? 200 : 503, result);
+}
+export async function buildRichHealthPayload(boot) {
+    if (boot.manager === undefined || boot.store === undefined) {
+        throw new Error("buildRichHealthPayload requires store and manager");
+    }
+    const capacity = await boot.manager.getHealthWithDisk();
+    const gitVersion = await probeGitVersion();
+    const schema = readSchemaHealth(boot.store);
+    const catalogRoots = await resolveCatalogRoots({
+        store: boot.store,
+        bootCwd: boot.cwd,
+    });
+    const payload = {
+        ...capacity,
+        capacity: {
+            global: {
+                activeRunIds: capacity.activeRunIds,
+                activeCount: capacity.activeCount,
+                maxConcurrent: capacity.maxConcurrent,
+                slotsAvailable: capacity.slotsAvailable,
+            },
+            per_project: boot.manager.getPerProjectCapacity(),
+        },
+        version: PACKAGE_VERSION,
+        build_sha: BUILD_SHA,
+        stageflow_home: globalStageflowHome(),
+        schema,
+        git_version: gitVersion ?? null,
+        toolchain: toolchainHealthMap(),
+        store_filesystem: boot.storeFilesystem ?? null,
+        egress: buildEgressHealth(),
+        catalog_roots: catalogRoots.map((r) => ({
+            project_root: r.project_root,
+            kind: r.kind,
+            read_only: r.read_only,
+        })),
+        providers: boot.providerBoot
+            ? {
+                configured: boot.providerBoot.configured,
+                failures: boot.providerBoot.failures,
+            }
+            : { configured: [], failures: [] },
+    };
+    if (boot.hostConfig) {
+        payload.config = redactHostConfig(boot.hostConfig);
+    }
+    if (boot.a2a?.status) {
+        payload.a2a = boot.a2a.status;
+    }
+    return payload;
+}
+export async function handleApiHealth(_req, res, boot) {
+    json(res, 200, await buildRichHealthPayload(boot));
+}

package/dist/server/http.d.ts

@@ -4,7 +4,10 @@ import type { RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
+import { type AllowedHosts } from "./allowedHosts.js";
+import { type ControlTokens } from "./controlToken.js";
 import { DEFAULT_PORT, type HttpHostEnvelope, type HttpHostRouteContext } from "./createHttpHost.js";
+import { type ShutdownController } from "./shutdown.js";
 export type UiServerOptions = {
     agent: AgentPort;
     cwd?: string;
@@ -19,6 +22,8 @@ export type UiServerOptions = {
     providerAuthContext?: ProviderAuthContext;
     mcpStateless?: boolean;
     runChangeBus?: RunChangeBus;
+    allowedHosts?: AllowedHosts;
+    controlTokens?: ControlTokens;
 };
 export declare function defaultUiDistDir(): string;
 export type OperatorRouteDeps = {
@@ -30,6 +35,10 @@ export type OperatorRouteDeps = {
     providerAuthContext: ProviderAuthContext | undefined;
     /** Omit for a headless service (e.g. `sf mcp`) — GETs outside the API surface just 404. */
     uiDistDir?: string;
+    allowedHosts?: AllowedHosts;
+    controlTokens?: ControlTokens;
+    /** Live shutdown controller; set after listen so restore can beginDrain. */
+    getShutdown?: () => import("./shutdown.js").ShutdownController | undefined;
 };
 /**
  * The full operator-console route surface: REST API (runs, stages,
@@ -39,5 +48,7 @@ export type OperatorRouteDeps = {
  * API; only the former needs the UI files.
  */
 export declare function createOperatorRoutes(deps: OperatorRouteDeps): (ctx: HttpHostRouteContext) => Promise<boolean | void>;
-export declare function startUiServer(options: UiServerOptions): Promise<HttpHostEnvelope>;
+export declare function startUiServer(options: UiServerOptions): Promise<HttpHostEnvelope & {
+    shutdown: ShutdownController;
+}>;
 export { DEFAULT_PORT };