stageflow 0.27.0 → 0.31.0

package/dist/runtime/triggerRunner.d.ts

@@ -0,0 +1,17 @@
+import type { RunStore } from "../runstore/port.js";
+import type { RunManager, StartRunResult } from "./runManager.js";
+import type { TaskFile } from "../types/task.js";
+/**
+ * Resolves a trigger id to its `*.trigger.yaml` catalog definition, resolves its
+ * `pipeline`/`task` refs to catalog files, and starts a real run through
+ * `RunManager.startRun` — the same internal entry point the CLI/MCP/console use.
+ * On a successful start, records the fire on the trigger's store row.
+ *
+ * `task` presence on the trigger definition is the either/or mode switch: a
+ * catalog-mode trigger (`task` set) rejects a supplied `options.task`; a
+ * dynamic-mode trigger (`task` absent) requires one.
+ */
+export declare function fireTrigger(triggerId: string, store: RunStore, runManager: RunManager, options?: {
+    cwd?: string;
+    task?: TaskFile;
+}): Promise<StartRunResult>;

package/dist/runtime/triggerRunner.js

@@ -0,0 +1,89 @@
+import path from "node:path";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { getCatalogScanPaths } from "../config/browseCatalog.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { findCatalogPathById, findTriggerDefinition } from "./triggerCatalog.js";
+/**
+ * Resolves a trigger id to its `*.trigger.yaml` catalog definition, resolves its
+ * `pipeline`/`task` refs to catalog files, and starts a real run through
+ * `RunManager.startRun` — the same internal entry point the CLI/MCP/console use.
+ * On a successful start, records the fire on the trigger's store row.
+ *
+ * `task` presence on the trigger definition is the either/or mode switch: a
+ * catalog-mode trigger (`task` set) rejects a supplied `options.task`; a
+ * dynamic-mode trigger (`task` absent) requires one.
+ */
+export async function fireTrigger(triggerId, store, runManager, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const ctx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+    const scanPaths = await getCatalogScanPaths(ctx);
+    if (!scanPaths) {
+        return { ok: false, reason: "No Stageflow catalog found", status: 404 };
+    }
+    const found = await findTriggerDefinition(scanPaths.triggerPaths, triggerId);
+    if (!found) {
+        return { ok: false, reason: `Trigger not found: ${triggerId}`, status: 404 };
+    }
+    const { path: triggerPath, definition: trigger } = found;
+    if (!trigger.enabled) {
+        return { ok: false, reason: `Trigger is disabled: ${triggerId}`, status: 409 };
+    }
+    const suppliedTask = options.task;
+    if (trigger.task !== undefined && suppliedTask !== undefined) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" already has a catalog task "${trigger.task}"; task override is not allowed`,
+            status: 422,
+            code: "trigger.task_override_not_allowed",
+        };
+    }
+    if (trigger.task === undefined && suppliedTask === undefined) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" has no catalog task; a task must be supplied when firing`,
+            status: 422,
+            code: "trigger.task_required",
+        };
+    }
+    const pipelinePath = await findCatalogPathById(scanPaths.pipelinePaths, trigger.pipeline);
+    if (!pipelinePath) {
+        return {
+            ok: false,
+            reason: `Trigger "${triggerId}" references unknown pipeline "${trigger.pipeline}"`,
+            status: 400,
+        };
+    }
+    let taskInput;
+    if (trigger.task !== undefined) {
+        const taskPath = await findCatalogPathById(scanPaths.taskPaths, trigger.task);
+        if (!taskPath) {
+            return {
+                ok: false,
+                reason: `Trigger "${triggerId}" references unknown task "${trigger.task}"`,
+                status: 400,
+            };
+        }
+        taskInput = taskPath;
+    }
+    else {
+        taskInput = suppliedTask;
+    }
+    const projectRoot = ctx.projectRoot ?? undefined;
+    const definitionRef = projectRoot !== undefined
+        ? path.relative(projectRoot, triggerPath).replace(/\\/g, "/")
+        : triggerPath;
+    await store.upsertTrigger({
+        id: triggerId,
+        definitionRef,
+        enabled: trigger.enabled,
+    });
+    const started = await runManager.startRun({
+        pipeline: pipelinePath,
+        task: taskInput,
+        ...(projectRoot !== undefined ? { projectRoot } : {}),
+    });
+    if (started.ok) {
+        await store.recordTriggerFired(triggerId, started.runId);
+    }
+    return started;
+}

package/dist/runtime/verifiedStageExecution.d.ts

@@ -2,6 +2,8 @@ import type { StageRunResult } from "../agent/port.js";
 import type { RunStore } from "../runstore/port.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
 import type { StageConfig } from "../types/stage.js";
+import type { BrowserRunner } from "../browser/browserHost.js";
+import { type LoginCheckConfig, type LoginCheckOptions } from "../browser/loginCheck.js";
 import type { StageRoots } from "./stageRoots.js";
 /** Sidecar written before completion command checks so they can inspect fork_choice. */
 export declare const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
@@ -29,4 +31,9 @@ export declare function createVerifiedStageExecution(options: {
     dag?: ResolvedPipelineDag;
     roots: StageRoots;
     commandEnv?: NodeJS.ProcessEnv;
+    browserLogin?: {
+        check: LoginCheckConfig;
+        runner?: BrowserRunner;
+        options?: LoginCheckOptions;
+    };
 }): VerifiedStageExecution;

package/dist/runtime/verifiedStageExecution.js

@@ -9,6 +9,9 @@ import { COMPLETION_VERIFICATION_FAILURE_PREFIX, } from "../types/completion.js"
 import { runCompletionContract, } from "./completionCheckRunner.js";
 import { readCompletionCheckoutBaseline, writeCompletionCheckoutBaseline, } from "./completionCheckoutBaseline.js";
 import { createGitCheckoutCapability } from "./gitCheckoutCapability.js";
+import { readStagePersistedBrowserEnv } from "../browser/stageBrowserEnv.js";
+import { defaultBrowserRunner } from "../browser/browserTeardown.js";
+import { runLoginCheck, } from "../browser/loginCheck.js";
 /** Sidecar written before completion command checks so they can inspect fork_choice. */
 export const COMPLETION_CANDIDATE_ENVELOPE_FILENAME = "completion-candidate-envelope.json";
 export function completionVerificationFailureReason(failedCheckIds) {
@@ -88,6 +91,17 @@ export function createVerifiedStageExecution(options) {
                     checkoutBefore,
                     checkoutError,
                     checklistAttestations: candidate.envelope.checklist_attestations,
+                    ...(options.browserLogin !== undefined
+                        ? {
+                            browserLogin: async () => {
+                                const env = await readStagePersistedBrowserEnv(roots.runWorkspaceDir, stageId);
+                                if (env === undefined) {
+                                    throw new Error("browser session env is missing for this stage");
+                                }
+                                return runLoginCheck(env, options.browserLogin.check, options.browserLogin.runner ?? defaultBrowserRunner, options.browserLogin.options);
+                            },
+                        }
+                        : {}),
                     onCheckStart: async (check) => {
                         await store.upsertVerificationCheckResult(runId, stageId, {
                             check_id: check.id,

package/dist/runtime/webhookSignature.d.ts

@@ -0,0 +1 @@
+export declare function verifyHmacSignature(rawBody: Buffer, headerValue: string, secret: string, scheme: "hex" | "base64"): boolean;

package/dist/runtime/webhookSignature.js

@@ -0,0 +1,12 @@
+import crypto from "node:crypto";
+export function verifyHmacSignature(rawBody, headerValue, secret, scheme) {
+    const eqIndex = headerValue.indexOf("=");
+    const hasPrefix = eqIndex !== -1 && eqIndex < headerValue.length - 1;
+    const provided = hasPrefix ? headerValue.slice(eqIndex + 1) : headerValue;
+    const computed = crypto.createHmac("sha256", secret).update(rawBody).digest(scheme);
+    const providedBuffer = Buffer.from(provided, scheme);
+    const computedBuffer = Buffer.from(computed, scheme);
+    if (providedBuffer.length !== computedBuffer.length)
+        return false;
+    return crypto.timingSafeEqual(providedBuffer, computedBuffer);
+}

package/dist/server/bootstrap.d.ts

@@ -45,6 +45,12 @@ export type StageflowHostBootstrap = {
     /** Periodic retention GC handle when enabled; already `.unref()`'d. */
     gcInterval?: NodeJS.Timeout;
     stopGcInterval: () => void;
+    /** Stops the schedule-trigger tick loop started at boot. */
+    stopScheduleSource: () => void;
+    /** Stops the GitHub poll-trigger loop started at boot. */
+    stopGithubPollSource: () => void;
+    /** Stops the email-trigger IMAP/IDLE listeners started at boot. */
+    stopEmailSource: () => void;
     /** Filesystem classification for `$STAGEFLOW_HOME` (Slot 8). */
     storeFilesystem?: StoreFilesystemClassification;
     /**

package/dist/server/bootstrap.js

@@ -12,10 +12,15 @@ import { assertStoreFilesystemSupported } from "../runstore/storeFilesystem.js";
 import { assertStoreQuickCheck, isSqliteCorruptError, maybeCheckpointResidualWal, rethrowAsStoreIntegrityFailed, } from "../runstore/sqlite/applyStorePragmas.js";
 import { RunManager } from "../runtime/runManager.js";
 import { PI_CODING_AGENT_DIR_ENV } from "../runtime/stageRoots.js";
+import { ScheduleSource, triggerTickIntervalMsFromEnv, } from "../runtime/scheduleSource.js";
+import { GithubPollSource, githubPollIntervalMsFromEnv, } from "../runtime/githubPollSource.js";
+import { EmailSource } from "../runtime/emailSource.js";
+import { fireTrigger } from "../runtime/triggerRunner.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
 import { loadHostConfig, } from "../config/hostConfig.js";
 import { bootProviderConfig } from "../agent/bootProviderConfig.js";
+import { readCursorApiKey } from "../agent/cursorProvider.js";
 import { applyPendingRestoreAtBoot, } from "../runstore/restore.js";
 import { assertTmpdirUsable } from "../runstore/assertTmpdir.js";
 import { logger as rootLogger } from "../logging/logger.js";
@@ -76,6 +81,11 @@ export async function bootstrapStageflowHost(options) {
     const ctx = await resolveStageflowContext(invocationCwd);
     const cwd = ctx.invocationCwd;
     ensureGlobalHome();
+    const cursorKey = readCursorApiKey(env);
+    if (cursorKey !== undefined &&
+        (env.CURSOR_API_KEY === undefined || env.CURSOR_API_KEY.trim() === "")) {
+        process.env.CURSOR_API_KEY = cursorKey;
+    }
     assertTmpdirUsable(env);
     const hostConfig = options.hostConfig ??
         (options.skipHostConfig
@@ -149,6 +159,9 @@ export async function bootstrapStageflowHost(options) {
                 close: async () => { },
             },
             stopGcInterval: () => { },
+            stopScheduleSource: () => { },
+            stopGithubPollSource: () => { },
+            stopEmailSource: () => { },
             storeFilesystem,
             serveBlocked,
             ...(hostConfig !== undefined ? { hostConfig } : {}),
@@ -231,6 +244,7 @@ export async function bootstrapStageflowHost(options) {
     });
     await manager.attachWaitingStages();
     await manager.reconcileOrphanedStages();
+    await manager.sweepBrowserSessions().catch(() => undefined);
     await manager.autoResumeInterruptedStages();
     await manager.resumeStalledSchedules();
     await manager.reenqueuePersistedQueuedRuns();
@@ -240,6 +254,58 @@ export async function bootstrapStageflowHost(options) {
         if (gcInterval !== undefined)
             clearInterval(gcInterval);
     };
+    const scheduleSource = new ScheduleSource({
+        store,
+        cwd,
+        intervalMs: triggerTickIntervalMsFromEnv(env),
+        logError: (message) => bootLog.error("trigger.schedule_source_failed", message),
+    });
+    const onTriggerFire = async (event) => {
+        try {
+            const result = await fireTrigger(event.triggerId, store, manager, {
+                cwd,
+                task: event.task,
+            });
+            if (!result.ok) {
+                bootLog.error("trigger.fire_failed", `trigger "${event.triggerId}" fire failed: ${result.reason}`);
+            }
+        }
+        catch (err) {
+            bootLog.error("trigger.fire_failed", `trigger "${event.triggerId}" fire threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    try {
+        // Boot-time catch-up: fire once for any schedule trigger whose next_run_at
+        // already passed while the Host was down, then reschedule from now —
+        // before starting the periodic ticker so this pass never races it.
+        await scheduleSource.tick(onTriggerFire);
+    }
+    catch (err) {
+        bootLog.error("trigger.schedule_catchup_failed", `boot catch-up tick failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    await scheduleSource.start(onTriggerFire);
+    const stopScheduleSource = () => {
+        void scheduleSource.stop();
+    };
+    const githubPollSource = new GithubPollSource({
+        store,
+        cwd,
+        intervalMs: githubPollIntervalMsFromEnv(env),
+        logError: (message) => bootLog.error("trigger.github_poll_source_failed", message),
+    });
+    await githubPollSource.start(onTriggerFire);
+    const stopGithubPollSource = () => {
+        void githubPollSource.stop();
+    };
+    const emailSource = new EmailSource({
+        store,
+        cwd,
+        logError: (message) => bootLog.error("trigger.email_source_failed", message),
+    });
+    await emailSource.start(onTriggerFire);
+    const stopEmailSource = () => {
+        void emailSource.stop();
+    };
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
     });
@@ -251,6 +317,7 @@ export async function bootstrapStageflowHost(options) {
         runChangeBus,
         providerAuthContext: options.providerAuthContext,
         projectRoot: rootDir,
+        ...(providerBoot !== undefined ? { providerBoot } : {}),
     }, { mcpStateless });
     return {
         a2a: await createA2aHost({
@@ -274,6 +341,9 @@ export async function bootstrapStageflowHost(options) {
         ...(providerBoot !== undefined ? { providerBoot } : {}),
         ...(gcInterval !== undefined ? { gcInterval } : {}),
         stopGcInterval,
+        stopScheduleSource,
+        stopGithubPollSource,
+        stopEmailSource,
         storeFilesystem,
     };
 }

package/dist/server/controlToken.js

@@ -158,11 +158,24 @@ export class BindRefusedError extends Error {
         this.name = "BindRefusedError";
     }
 }
+/**
+ * `POST /api/triggers/:id/webhook` is exempt from bearer auth: an external
+ * webhook sender can't present Stageflow's own control token, and the route
+ * authenticates the request itself via per-trigger HMAC signature
+ * verification instead. It still goes through `assertAllowedHttpAccess`
+ * (loopback/allowed-hosts gating) the same as every other `/api/*` route —
+ * only the bearer-token requirement is carved out here.
+ */
+function isTriggerWebhookRoute(method, pathname) {
+    return method === "POST" && /^\/api\/triggers\/[^/]+\/webhook$/.test(pathname);
+}
 export function requiredScopeFor(method, pathname) {
     if (pathname === "/mcp")
         return "drive";
     if (!pathname.startsWith("/api/"))
         return null;
+    if (isTriggerWebhookRoute(method, pathname))
+        return null;
     if (pathname === "/api/backup" || pathname.startsWith("/api/backup/")) {
         return "drive";
     }

package/dist/server/createHttpHost.js

@@ -135,6 +135,9 @@ export async function createHttpHost(options) {
     server.maxConnections = maxConnections;
     server.on("close", () => {
         boot.stopGcInterval();
+        boot.stopScheduleSource();
+        boot.stopGithubPollSource();
+        boot.stopEmailSource();
         void boot.mcpHandler.close();
     });
     await new Promise((resolve, reject) => {

package/dist/server/healthSurfaces.js

@@ -1,3 +1,4 @@
+import { getAuthStatus, } from "../agent/providerAuth.js";
 import { PACKAGE_VERSION, BUILD_SHA } from "../package-meta.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { redactHostConfig } from "../config/hostConfig.js";
@@ -6,6 +7,31 @@ 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";
+function bootProvidersSnapshot(providerBoot) {
+    return providerBoot
+        ? {
+            configured: providerBoot.configured,
+            failures: providerBoot.failures,
+        }
+        : { configured: [], failures: [] };
+}
+async function providersLiveSummary(cwd, authCtx) {
+    const note = "Live auth inspect — prefer list_providers / sf providers status. boot_providers is Host boot env only and may be empty when CLI credentials are configured.";
+    if (authCtx === undefined) {
+        return { configured: [], note };
+    }
+    try {
+        const status = await getAuthStatus(cwd, undefined, authCtx);
+        const rows = Array.isArray(status) ? status : [status];
+        return {
+            configured: rows.filter((r) => r.configured).map((r) => r.providerId),
+            note,
+        };
+    }
+    catch {
+        return { configured: [], note };
+    }
+}
 export function handleLivez(_req, res) {
     json(res, 200, livezBody());
 }
@@ -54,6 +80,8 @@ export async function buildRichHealthPayload(boot) {
         store: boot.store,
         bootCwd: boot.cwd,
     });
+    const boot_providers = bootProvidersSnapshot(boot.providerBoot);
+    const providers_live = await providersLiveSummary(boot.cwd, boot.providerAuthContext);
     const payload = {
         ...capacity,
         capacity: {
@@ -78,12 +106,9 @@ export async function buildRichHealthPayload(boot) {
             kind: r.kind,
             read_only: r.read_only,
         })),
-        providers: boot.providerBoot
-            ? {
-                configured: boot.providerBoot.configured,
-                failures: boot.providerBoot.failures,
-            }
-            : { configured: [], failures: [] },
+        boot_providers,
+        providers_live,
+        providers: boot_providers,
     };
     if (boot.hostConfig) {
         payload.config = redactHostConfig(boot.hostConfig);

package/dist/server/http.d.ts

@@ -1,5 +1,7 @@
 import type { AgentPort } from "../agent/port.js";
 import { type ProviderAuthContext } from "../agent/providerAuth.js";
+import { WorkshopChatSessionRegistry } from "../workshop/chatTurn.js";
+import { type OperatorAgentHost } from "../operatorAgent/index.js";
 import type { RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
@@ -24,6 +26,8 @@ export type UiServerOptions = {
     runChangeBus?: RunChangeBus;
     allowedHosts?: AllowedHosts;
     controlTokens?: ControlTokens;
+    /** Optional Workshop Operator Agent Host (fake in tests). */
+    workshopOperatorHost?: OperatorAgentHost;
 };
 export declare function defaultUiDistDir(): string;
 export type OperatorRouteDeps = {
@@ -39,6 +43,17 @@ export type OperatorRouteDeps = {
     controlTokens?: ControlTokens;
     /** Live shutdown controller; set after listen so restore can beginDrain. */
     getShutdown?: () => import("./shutdown.js").ShutdownController | undefined;
+    /**
+     * Optional Operator Agent Host for Workshop chat (tests inject the fake host).
+     * Distinct from stage-execution AgentPort. Defaults to live Pi Workshop Author
+     * (fake remains available via createWorkshopOperatorHost / test injection).
+     */
+    workshopOperatorHost?: OperatorAgentHost;
+    /**
+     * Optional durable Workshop chat registry (host sessions keyed by session id).
+     * Defaults to a registry owned by this route surface.
+     */
+    workshopChatRegistry?: WorkshopChatSessionRegistry;
 };
 /**
  * The full operator-console route surface: REST API (runs, stages,