stageflow 0.25.0 → 0.30.0

package/dist/server/listenHost.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveListenHost(options: {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function advertisedHost(bind: string): string;

package/dist/server/listenHost.js

@@ -0,0 +1,56 @@
+import { isIP } from "node:net";
+const DEFAULT_BIND = "127.0.0.1";
+export function resolveListenHost(options) {
+    const env = options.env ?? process.env;
+    let raw;
+    if (options.flag !== undefined) {
+        raw = options.flag;
+    }
+    else if (env.STAGEFLOW_BIND !== undefined) {
+        raw = env.STAGEFLOW_BIND;
+    }
+    if (raw === undefined) {
+        return DEFAULT_BIND;
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        throw new Error(`Invalid --host / STAGEFLOW_BIND value: ${JSON.stringify(raw)}. Use an IPv4 or IPv6 literal, 0.0.0.0, or ::.`);
+    }
+    const normalized = unwrapIpv6Brackets(value);
+    if (value.includes("://") ||
+        value.includes("/") ||
+        looksLikeHostPort(value) ||
+        isIP(normalized) === 0) {
+        throw new Error(`Invalid --host / STAGEFLOW_BIND value: ${JSON.stringify(value)}. Use an IPv4 or IPv6 literal, 0.0.0.0, or ::.`);
+    }
+    return normalized;
+}
+export function advertisedHost(bind) {
+    if (bind === "0.0.0.0")
+        return "127.0.0.1";
+    if (bind === "::")
+        return "[::1]";
+    if (isIP(bind) === 6)
+        return `[${bind}]`;
+    return bind;
+}
+function unwrapIpv6Brackets(value) {
+    if (value.startsWith("[") && value.endsWith("]")) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function looksLikeHostPort(value) {
+    if (value.startsWith("[")) {
+        const end = value.indexOf("]");
+        if (end === -1)
+            return false;
+        const rest = value.slice(end + 1);
+        return rest.startsWith(":") && rest.length > 1;
+    }
+    const colon = value.lastIndexOf(":");
+    if (colon <= 0)
+        return false;
+    const maybePort = value.slice(colon + 1);
+    return /^\d+$/.test(maybePort) && isIP(value.slice(0, colon)) !== 0;
+}

package/dist/server/mcpHost.d.ts

@@ -3,7 +3,10 @@ import type { ProviderAuthContext } from "../agent/providerAuth.js";
 import type { RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.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 } from "./createHttpHost.js";
+import { type ShutdownController } from "./shutdown.js";
 export type McpServerOptions = {
     agent: AgentPort;
     cwd?: string;
@@ -17,6 +20,12 @@ export type McpServerOptions = {
     providerAuthContext?: ProviderAuthContext;
     mcpStateless?: boolean;
     runChangeBus?: RunChangeBus;
+    allowedHosts?: AllowedHosts;
+    controlTokens?: ControlTokens;
+    requestTimeoutMs?: number;
+    maxConnections?: number;
 };
-export declare function startMcpServer(options: McpServerOptions): Promise<HttpHostEnvelope>;
+export declare function startMcpServer(options: McpServerOptions): Promise<HttpHostEnvelope & {
+    shutdown: ShutdownController;
+}>;
 export { DEFAULT_PORT };

package/dist/server/mcpHost.js

@@ -1,20 +1,50 @@
 import { bootstrapStageflowHost, } from "./bootstrap.js";
+import { resolveAllowedHosts } from "./allowedHosts.js";
+import { loadControlTokens } from "./controlToken.js";
 import { createHttpHost, DEFAULT_PORT, } from "./createHttpHost.js";
 import { createOperatorRoutes } from "./http.js";
+import { installShutdownController, makeDrainableHostFromOptional, } from "./shutdown.js";
 export async function startMcpServer(options) {
     const host = options.host ?? "127.0.0.1";
     const port = options.port ?? DEFAULT_PORT;
     const boot = await bootstrapStageflowHost(options);
-    const { manager, store, cwd, agentDir, rootDir } = boot;
+    const { cwd, agentDir, rootDir } = boot;
     const providerAuthContext = boot.providerAuthContext;
-    return createHttpHost({
+    const allowedHosts = options.allowedHosts ?? resolveAllowedHosts();
+    const controlTokens = options.controlTokens ?? loadControlTokens();
+    let shutdown;
+    const routes = boot.serveBlocked !== undefined ||
+        boot.manager === undefined ||
+        boot.store === undefined
+        ? async () => false
+        : createOperatorRoutes({
+            manager: boot.manager,
+            store: boot.store,
+            cwd,
+            agentDir,
+            rootDir,
+            providerAuthContext,
+            allowedHosts,
+            controlTokens,
+            getShutdown: () => shutdown,
+        });
+    const envelope = await createHttpHost({
         boot,
         host,
         port,
-        // Headless daemon: same REST API surface as `sf ui` (this is what lets
-        // `sf run`/`sf runs *` talk to an auto-started `sf mcp` over HTTP), just
-        // without serving the console's static UI files.
-        routes: createOperatorRoutes({ manager, store, cwd, agentDir, rootDir, providerAuthContext }),
+        allowedHosts,
+        controlTokens,
+        requestTimeoutMs: options.requestTimeoutMs,
+        maxConnections: options.maxConnections,
+        routes,
     });
+    shutdown = installShutdownController({
+        server: envelope.server,
+        host: makeDrainableHostFromOptional(envelope.manager, envelope.store),
+    });
+    envelope.server.on("close", () => {
+        shutdown?.uninstall();
+    });
+    return { ...envelope, shutdown };
 }
 export { DEFAULT_PORT };

package/dist/server/operatorResults.d.ts

@@ -1,10 +1,9 @@
 import type { RetryStageResult, StartRunResult } from "../runtime/runManager.js";
-export declare function inferRetryStageErrorCode(reason: string): string | undefined;
 export declare function mapRetryStageFailure(result: Extract<RetryStageResult, {
     ok: false;
 }>): {
     error: string;
-    code?: string;
+    code: string;
 } & Record<string, unknown>;
 export declare function mapStartFailure(result: Extract<StartRunResult, {
     ok: false;
@@ -17,6 +16,7 @@ export type StoreLookupMapped = {
     error: string;
     status: number;
     kind: StoreLookupKind;
+    code: string;
 };
 export declare function mapStoreLookupError(err: unknown, opts: {
     policy: StoreLookupPolicy;

package/dist/server/operatorResults.js

@@ -1,48 +1,59 @@
-export function inferRetryStageErrorCode(reason) {
-    if (/retry already in progress/i.test(reason))
-        return "retry_in_progress";
-    if (/waiting for input/i.test(reason))
-        return "hitl_not_retriable";
-    if (/already has active orchestration/i.test(reason))
-        return "run_not_retryable";
-    if (/run is not failed/i.test(reason))
-        return "run_not_retryable";
-    if (/stage is not failed/i.test(reason))
-        return "stage_not_failed";
-    if (/manual recovery/i.test(reason))
-        return "manual_recovery_required";
-    return undefined;
-}
+import { codeOrInternal } from "../errors/codes.js";
 export function mapRetryStageFailure(result) {
-    const { ok: _ok, status: _status, reason, ...rest } = result;
-    const code = inferRetryStageErrorCode(reason);
-    return { error: reason, ...(code ? { code } : {}), ...rest };
+    const { ok: _ok, status: _status, reason, code, ...rest } = result;
+    return { error: reason, code: codeOrInternal(code), ...rest };
 }
 export function mapStartFailure(result) {
     const { ok: _ok, status: _status, reason, ...rest } = result;
     return { error: reason, ...rest };
 }
-export function mapStoreLookupError(err, opts) {
-    const error = err instanceof Error ? err.message : String(err);
-    if (opts.policy === "artifact") {
+function storeLookupCode(kind, policy) {
+    if (kind === "denied")
+        return "artifact_path_denied";
+    if (kind === "not_found") {
+        if (policy === "artifact")
+            return "artifact_not_found";
+        if (policy === "envelope")
+            return "envelope_not_found";
+        return "run_not_found";
+    }
+    return "internal_error";
+}
+function classifyStoreMessage(error, policy) {
+    if (policy === "artifact") {
         if (error === "Artifact path denied") {
-            return { error, status: 400, kind: "denied" };
+            return { kind: "denied", status: 400 };
         }
         const notFound = error.startsWith("Run not found") ||
             error.startsWith("Artifact not found") ||
-            /no such|not found/i.test(error);
+            error.startsWith("Checkout file not found");
         return {
-            error,
+            kind: notFound ? "not_found" : "error",
             status: notFound ? 404 : 400,
+        };
+    }
+    if (policy === "envelope") {
+        const notFound = error.startsWith("Envelope not found") ||
+            error.startsWith("Run not found") ||
+            error.startsWith("Stage execution not found");
+        return {
             kind: notFound ? "not_found" : "error",
+            status: notFound ? 404 : 500,
         };
     }
-    const notFound = opts.policy === "envelope"
-        ? /not found|no such|envelope/i.test(error)
-        : /not found|no such|unknown run/i.test(error);
+    const notFound = error.startsWith("Run not found") || error.startsWith("unknown run");
     return {
-        error,
-        status: notFound ? 404 : 500,
         kind: notFound ? "not_found" : "error",
+        status: notFound ? 404 : 500,
+    };
+}
+export function mapStoreLookupError(err, opts) {
+    const error = err instanceof Error ? err.message : String(err);
+    const classified = classifyStoreMessage(error, opts.policy);
+    return {
+        error,
+        status: classified.status,
+        kind: classified.kind,
+        code: storeLookupCode(classified.kind, opts.policy),
     };
 }

package/dist/server/requestAuthContext.d.ts

@@ -0,0 +1,12 @@
+import type { BearerAuth, ControlScope } from "./controlToken.js";
+export type CallerSurface = "mcp" | "rest" | "cli" | "a2a" | "webhook";
+export type RequestAuthContext = {
+    scope: ControlScope;
+    caller_id: string;
+    surface: CallerSurface;
+};
+export declare function runWithRequestAuth<T>(auth: RequestAuthContext | null, fn: () => T): T;
+export declare function getRequestAuth(): RequestAuthContext | null;
+export declare function requestAuthFromBearer(bearer: BearerAuth | undefined, surface: CallerSurface): RequestAuthContext | null;
+/** Attribution for createRun: auth caller only; CLI / open loopback → null. */
+export declare function callerIdFromRequestAuth(): string | null;

package/dist/server/requestAuthContext.js

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function runWithRequestAuth(auth, fn) {
+    return storage.run(auth, fn);
+}
+export function getRequestAuth() {
+    return storage.getStore() ?? null;
+}
+export function requestAuthFromBearer(bearer, surface) {
+    if (bearer === undefined)
+        return null;
+    return {
+        scope: bearer.scope,
+        caller_id: bearer.caller_id,
+        surface,
+    };
+}
+/** Attribution for createRun: auth caller only; CLI / open loopback → null. */
+export function callerIdFromRequestAuth() {
+    return getRequestAuth()?.caller_id ?? null;
+}

package/dist/server/shutdown.d.ts

@@ -0,0 +1,69 @@
+import type { Server } from "node:http";
+import { type Logger } from "../logging/logger.js";
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager } from "../runtime/runManager.js";
+export interface DrainableHost {
+    stopAcceptingWork(): void;
+    drainActiveStages(opts: {
+        deadlineMs: number;
+        isEscalated?: () => boolean;
+    }): Promise<{
+        forced: boolean;
+    }>;
+    closeStore(): Promise<void>;
+}
+export declare function makeDrainableHost(manager: RunManager, store: RunStore): DrainableHost;
+export declare function makeDrainableHostFromOptional(manager: RunManager | undefined, store: RunStore | undefined): DrainableHost;
+export declare const SHUTDOWN_GRACE_MS_ENV = "STAGEFLOW_SHUTDOWN_GRACE_MS";
+export declare const DEFAULT_SHUTDOWN_GRACE_MS = 8000;
+export declare const CHECKPOINT_RESERVE_MS = 2000;
+export declare const ESCALATION_CHECKPOINT_MS = 1000;
+export declare const HOST_EXIT: {
+    readonly CLEAN: 0;
+    readonly CRASH: 1;
+    readonly RESERVED: 2;
+    readonly BAD_CONFIG: 3;
+    readonly STORE_NEWER: 4;
+    readonly FORCED: 5;
+    readonly ESCALATED: 6;
+};
+export type HostExitCode = (typeof HOST_EXIT)[keyof typeof HOST_EXIT];
+export type HostDrainResult = {
+    exitCode: typeof HOST_EXIT.CLEAN | typeof HOST_EXIT.FORCED | typeof HOST_EXIT.ESCALATED;
+    forced: boolean;
+    escalated: boolean;
+};
+export type ShutdownControllerOptions = {
+    server: Server;
+    host: DrainableHost;
+    graceMs?: number;
+    env?: NodeJS.ProcessEnv;
+    logger?: Logger;
+    /** When false, callers drive drain via `beginDrain()` (tests). Default true. */
+    installSignals?: boolean;
+};
+export declare function parseShutdownGraceMs(env?: NodeJS.ProcessEnv): number;
+export declare function workerBudgetMs(graceMs: number): number;
+export declare class ShutdownController {
+    private readonly server;
+    private readonly host;
+    private readonly graceMs;
+    private readonly log;
+    private readonly installSignals;
+    private drainPromise;
+    private escalated;
+    private readonly escalateWaiters;
+    private installed;
+    private drainStarted;
+    constructor(options: ShutdownControllerOptions);
+    install(): void;
+    uninstall(): void;
+    /** Deliver a SIGTERM/SIGINT-equivalent (tests and supervisors). */
+    notifySignal(): void;
+    whenDrained(): Promise<HostDrainResult>;
+    beginDrain(): Promise<HostDrainResult>;
+    private readonly onSignal;
+    private waitUntil;
+    private runDrain;
+}
+export declare function installShutdownController(options: ShutdownControllerOptions): ShutdownController;

package/dist/server/shutdown.js

@@ -0,0 +1,219 @@
+import { logger as rootLogger, } from "../logging/logger.js";
+export function makeDrainableHost(manager, store) {
+    return {
+        stopAcceptingWork: () => manager.stopAcceptingWork(),
+        drainActiveStages: (opts) => manager.drainActiveStages(opts),
+        closeStore: () => store.close(),
+    };
+}
+const noopDrainableHost = {
+    stopAcceptingWork: () => { },
+    drainActiveStages: async () => ({ forced: false }),
+    closeStore: async () => { },
+};
+export function makeDrainableHostFromOptional(manager, store) {
+    if (manager !== undefined && store !== undefined) {
+        return makeDrainableHost(manager, store);
+    }
+    return noopDrainableHost;
+}
+export const SHUTDOWN_GRACE_MS_ENV = "STAGEFLOW_SHUTDOWN_GRACE_MS";
+export const DEFAULT_SHUTDOWN_GRACE_MS = 8000;
+export const CHECKPOINT_RESERVE_MS = 2000;
+export const ESCALATION_CHECKPOINT_MS = 1000;
+export const HOST_EXIT = {
+    CLEAN: 0,
+    CRASH: 1,
+    RESERVED: 2,
+    BAD_CONFIG: 3,
+    STORE_NEWER: 4,
+    FORCED: 5,
+    ESCALATED: 6,
+};
+export function parseShutdownGraceMs(env = process.env) {
+    const raw = env[SHUTDOWN_GRACE_MS_ENV]?.trim();
+    if (raw === undefined || raw === "") {
+        return DEFAULT_SHUTDOWN_GRACE_MS;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_SHUTDOWN_GRACE_MS;
+    }
+    return Math.floor(parsed);
+}
+export function workerBudgetMs(graceMs) {
+    return Math.max(0, graceMs - CHECKPOINT_RESERVE_MS);
+}
+export class ShutdownController {
+    server;
+    host;
+    graceMs;
+    log;
+    installSignals;
+    drainPromise;
+    escalated = false;
+    escalateWaiters = new Set();
+    installed = false;
+    drainStarted;
+    constructor(options) {
+        this.server = options.server;
+        this.host = options.host;
+        this.graceMs =
+            options.graceMs ?? parseShutdownGraceMs(options.env ?? process.env);
+        this.log =
+            options.logger ?? rootLogger.child({ component: "shutdown" });
+        this.installSignals = options.installSignals !== false;
+    }
+    install() {
+        if (!this.installSignals || this.installed)
+            return;
+        this.installed = true;
+        process.on("SIGTERM", this.onSignal);
+        process.on("SIGINT", this.onSignal);
+    }
+    uninstall() {
+        if (!this.installed)
+            return;
+        this.installed = false;
+        process.off("SIGTERM", this.onSignal);
+        process.off("SIGINT", this.onSignal);
+    }
+    /** Deliver a SIGTERM/SIGINT-equivalent (tests and supervisors). */
+    notifySignal() {
+        this.onSignal();
+    }
+    whenDrained() {
+        if (this.drainPromise !== undefined) {
+            return this.drainPromise;
+        }
+        if (this.drainStarted === undefined) {
+            let resolve;
+            const promise = new Promise((r) => {
+                resolve = r;
+            });
+            this.drainStarted = { resolve, promise };
+        }
+        return this.drainStarted.promise.then((p) => p);
+    }
+    beginDrain() {
+        if (this.drainPromise !== undefined) {
+            return this.drainPromise;
+        }
+        this.drainPromise = this.runDrain();
+        if (this.drainStarted === undefined) {
+            let resolve;
+            const promise = new Promise((r) => {
+                resolve = r;
+            });
+            this.drainStarted = { resolve, promise };
+        }
+        this.drainStarted.resolve(this.drainPromise);
+        return this.drainPromise;
+    }
+    onSignal = () => {
+        if (this.drainPromise === undefined) {
+            this.log.info("host.shutdown.signal", "shutdown signal received", {
+                grace_ms: this.graceMs,
+            });
+            void this.beginDrain();
+            return;
+        }
+        if (this.escalated)
+            return;
+        this.escalated = true;
+        this.log.warn("host.shutdown.escalated", "second shutdown signal; escalating", { grace_ms: this.graceMs });
+        for (const wake of this.escalateWaiters) {
+            wake();
+        }
+        this.escalateWaiters.clear();
+    };
+    waitUntil(deadlineMs) {
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearInterval(timer);
+                this.escalateWaiters.delete(finish);
+                resolve();
+            };
+            const timer = setInterval(() => {
+                if (this.escalated || Date.now() >= deadlineMs) {
+                    finish();
+                }
+            }, 25);
+            this.escalateWaiters.add(finish);
+            if (this.escalated || Date.now() >= deadlineMs) {
+                finish();
+            }
+        });
+    }
+    async runDrain() {
+        const startedAt = Date.now();
+        const hardDeadline = startedAt + this.graceMs;
+        const workerDeadline = startedAt + workerBudgetMs(this.graceMs);
+        this.log.info("host.shutdown.drain_start", "beginning host drain", {
+            grace_ms: this.graceMs,
+            worker_budget_ms: workerBudgetMs(this.graceMs),
+        });
+        this.host.stopAcceptingWork();
+        try {
+            this.server.closeIdleConnections();
+        }
+        catch {
+            // older Node or already closing
+        }
+        const serverClosed = new Promise((resolve) => {
+            this.server.close(() => resolve());
+        });
+        const stageResult = await this.host.drainActiveStages({
+            deadlineMs: workerDeadline,
+            isEscalated: () => this.escalated,
+        });
+        const checkpointDeadline = this.escalated
+            ? Date.now() + ESCALATION_CHECKPOINT_MS
+            : hardDeadline;
+        let storeCloseFailed = false;
+        try {
+            await this.host.closeStore();
+        }
+        catch (err) {
+            storeCloseFailed = true;
+            this.log.error("host.shutdown.store_close_failed", err instanceof Error ? err.message : String(err));
+        }
+        await Promise.race([
+            serverClosed,
+            this.waitUntil(checkpointDeadline),
+        ]);
+        try {
+            this.server.closeAllConnections();
+        }
+        catch {
+            // ignore
+        }
+        await Promise.race([
+            serverClosed,
+            this.waitUntil(Date.now() + 100),
+        ]);
+        this.uninstall();
+        const forced = stageResult.forced || storeCloseFailed;
+        const exitCode = this.escalated
+            ? HOST_EXIT.ESCALATED
+            : forced
+                ? HOST_EXIT.FORCED
+                : HOST_EXIT.CLEAN;
+        this.log.info("host.shutdown.drain_complete", "host drain complete", {
+            exit_code: exitCode,
+            forced,
+            escalated: this.escalated,
+            elapsed_ms: Date.now() - startedAt,
+        });
+        return {
+            exitCode,
+            forced,
+            escalated: this.escalated,
+        };
+    }
+}
+export function installShutdownController(options) {
+    const controller = new ShutdownController(options);
+    controller.install();
+    return controller;
+}

package/dist/server/triggerRoutes.d.ts

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Logger } from "../logging/logger.js";
+import type { RunManager } from "../runtime/runManager.js";
+import type { RunStore } from "../runstore/port.js";
+export type { TriggerListItem } from "../config/triggerCatalog.js";
+export type TriggerRoutesCtx = {
+    cwd: string;
+    manager: RunManager;
+    store: RunStore;
+    json: (res: ServerResponse, status: number, body: unknown) => void;
+    readJsonBody: (req: IncomingMessage) => Promise<unknown>;
+    readRawBody: (req: IncomingMessage) => Promise<Buffer>;
+    auditLog: Logger;
+};
+export declare function handleTriggerRoutes(req: IncomingMessage, res: ServerResponse, ctx: TriggerRoutesCtx): Promise<boolean>;