stageflow 0.27.0 → 0.30.0

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,7 @@
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
+import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
+import { humanLoginPromptBlock, isHumanLoginStage } from "../browser/humanLogin.js";
+import { BROWSER_SKILL_NAME, resolveBuiltinSkillFile, } from "../config/builtinSkills.js";
 import { resolveSkillByName, } from "../config/listSkills.js";
 import { loadHostConfig } from "../config/hostConfig.js";
 import { defaultSeededRoots } from "../config/seededCatalog.js";
@@ -7,6 +10,7 @@ import { mkdir } from "node:fs/promises";
 import { runSkillsDir } from "./runSkills.js";
 import { MCP_CATALOG_FILENAME, STAGEFLOW_STAGE_ARTIFACTS_DIR_ENV, StageMcpError, mcpCatalogExists, mcpCatalogPath, resolveStageMcpServers, stampStagePromptArtifactsDir, } from "../config/resolveStageMcpServers.js";
 import { attemptArtifactsDir, attemptStreamLogPath } from "../runstore/workspaceLayout.js";
+import { redactBrowserActivityEvent, redactBrowserSecrets, } from "../agent/streamLogRedact.js";
 import { createStageStreamLogWriter, } from "./stageStreamLog.js";
 import { resolveCloneEmitContext, resolveForkEmitContext } from "../config/resolveForkEmitContext.js";
 import { createAttemptQaTrailReader } from "../hitl/qaTrail.js";
@@ -68,6 +72,17 @@ async function resolveStageSkillForRun(stage, catalog, options) {
         skillOrigin: resolved.origin,
     };
 }
+/** Browser stages get the `browser` skill (run > checkout > host > built-in). A missing skill is not an error. */
+async function resolveBrowserSkillFile(stage, catalog, options) {
+    if (stage.browser === undefined || stage.skill === BROWSER_SKILL_NAME) {
+        return undefined;
+    }
+    const resolved = await resolveStageSkillForRun({ skill: BROWSER_SKILL_NAME }, catalog, options);
+    if (resolved.ok && resolved.skillFilePath !== undefined) {
+        return resolved.skillFilePath;
+    }
+    return resolveBuiltinSkillFile(BROWSER_SKILL_NAME);
+}
 async function resolveAttemptMcpServers(allowlist, factoryCwd, artifactsDir, options) {
     const names = allowlist ?? [];
     if (names.length === 0)
@@ -151,6 +166,13 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
     });
     if (!skill.ok)
         return skill;
+    const browserSkillFilePath = await resolveBrowserSkillFile(input.stage, catalog, {
+        bindingKind: resolveOptions.bindingKind,
+        checkoutRoot: resolveOptions.checkoutRoot,
+        factoryCwd,
+        trustWorkspaceConfig: resolveOptions.trustWorkspaceConfig,
+        workspaceDir: resolveOptions.workspaceDir,
+    });
     let resolvedMcpServers;
     const origins = [];
     try {
@@ -207,16 +229,41 @@ async function openStageWithOperatorCatalog(agent, input, catalog, factoryCwd, a
             })).catch(() => null);
         }
     }
+    let loginCheck;
+    const humanLogin = isHumanLoginStage(resolveOptions.dag, input.stage.id, input.stage.browser);
+    if (input.stage.browser?.check !== undefined && !humanLogin) {
+        loginCheck = await readStageLoginCheck(resolveOptions.workspaceDir, stageIdForManifest);
+        if (loginCheck === undefined) {
+            return { ok: false, reason: "browser login check result is missing" };
+        }
+    }
     try {
         const handle = agent.openStage({
             ...input,
             stage: {
                 ...input.stage,
-                system_prompt: stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir),
+                system_prompt: `${stampStagePromptArtifactsDir(input.stage.system_prompt, artifactsDir)}${loginCheck !== undefined ? `\n\n${loginCheckPromptBlock(loginCheck)}` : ""}${humanLogin ? `\n\n${humanLoginPromptBlock(input.stage.browser?.login_url ?? input.stage.browser?.check?.url)}` : ""}`,
+                ...(loginCheck !== undefined
+                    ? {
+                        pre_emit_checks: [
+                            ...(input.stage.pre_emit_checks ?? []),
+                            {
+                                id: "browser_login_check",
+                                type: "browser_login_check",
+                                state: loginCheck.state,
+                                logged_in: loginCheck.logged_in,
+                                url: loginCheck.url,
+                            },
+                        ],
+                    }
+                    : {}),
             },
             ...(skill.skillFilePath !== undefined
                 ? { skillFilePath: skill.skillFilePath }
                 : {}),
+            ...(browserSkillFilePath !== undefined
+                ? { browserSkillFilePath }
+                : {}),
             ...(resolvedMcpServers !== undefined ? { resolvedMcpServers } : {}),
             onResolvedModel: async (info) => {
                 await patchRunManifest(resolveOptions.store, resolveOptions.runId, (m) => withStageResolvedModel(m, info.stageId, {
@@ -357,7 +404,10 @@ export async function openStageAttempt(input) {
         return priorInput;
     const roots = resolveAttemptRoots(input, stageId);
     const attempt = input.attemptCtx?.attempt ?? 1;
-    const streamWriter = (input.streamLogWriterFactory ?? createStageStreamLogWriter)(attemptStreamLogPath(input.workspaceDir, stageId, attempt));
+    const streamLogPath = attemptStreamLogPath(input.workspaceDir, stageId, attempt);
+    const streamWriter = input.streamLogWriterFactory
+        ? input.streamLogWriterFactory(streamLogPath)
+        : createStageStreamLogWriter(streamLogPath, input.stage.browser !== undefined ? { redact: redactBrowserSecrets } : {});
     const resumeToken = input.resumeToken ??
         resumeSessionFilePath(input.workspaceDir, stageId, attempt);
     const forkEmitContext = resolveForkEmitContext(input.dag, definitionId);
@@ -394,7 +444,9 @@ export async function openStageAttempt(input) {
         resumeToken,
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
-            input.onActivity?.(event);
+            input.onActivity?.(input.stage.browser !== undefined
+                ? redactBrowserActivityEvent(event)
+                : event);
             void streamWriter.flush();
         },
         onAssistantTextDelta: streamWriter.onDelta,

package/dist/runtime/stageEnvironment.js

@@ -25,6 +25,7 @@ export const STAGE_ENV_ALLOWLIST = [
     "https_proxy",
     "no_proxy",
     "STAGEFLOW_HOME",
+    "STAGEFLOW_CURSOR_EXTENSION",
 ];
 const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",

package/dist/runtime/stageHitl.d.ts

@@ -4,6 +4,7 @@ import { type StageAttemptContext } from "./stageAttemptContext.js";
 import { type AskOperatorPrompt } from "../tools/askOperator.js";
 export type DeliverAnswerResult = {
     ok: true;
+    verification?: "failed_retrying";
 } | {
     ok: false;
     reason: string;

package/dist/runtime/stageHitl.js

@@ -1,3 +1,4 @@
+import { parseHostGateContext } from "../browser/gateHandoff.js";
 import { appendOperatorAnswer, appendOperatorPrompt, derivePendingPrompt, } from "../hitl/qaTrail.js";
 import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
 import { attemptContext } from "./stageAttemptContext.js";
@@ -7,7 +8,10 @@ export function tryParsePendingPrompt(pendingRequest) {
         return undefined;
     }
     try {
-        return normalizePromptIds(parseAskOperatorParams(pendingRequest));
+        return {
+            ...normalizePromptIds(parseAskOperatorParams(pendingRequest)),
+            ...parseHostGateContext(pendingRequest),
+        };
     }
     catch {
         return undefined;

package/dist/runtime/stageProcessLauncher.d.ts

@@ -17,6 +17,7 @@ export type StageLaunchInput = {
     bindingKind?: DerivedBindingKind;
     grants?: ResolvedStageGrants;
     attemptHome?: string;
+    browserEnv?: Record<string, string>;
 };
 export type StageLaunchResult = {
     type: "succeeded";
@@ -45,6 +46,7 @@ export declare class StageProcessLauncher {
     private readonly env;
     private readonly explicitChildExtras;
     private readonly cliEntry;
+    private readonly workerExecArgv;
     private readonly logger;
     private readonly forkFn;
     private readonly active;

package/dist/runtime/stageProcessLauncher.js

@@ -1,7 +1,9 @@
 import * as childProcess from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { logger as rootLogger, resolveLogMaxLineBytes, } from "../logging/logger.js";
+import { BROWSER_ENV_PREFIX } from "../browser/browserHost.js";
 import { PACKAGE_VERSION } from "../package-meta.js";
+import { PI_HOME_AUTH_PATH_ENV, piHomeAuthPath } from "./credentialBinding.js";
 import { redactString } from "../logging/redact.js";
 import { getNamedSecrets } from "../logging/namedSecrets.js";
 import { readMaxActiveStageProcesses, } from "./stageConcurrency.js";
@@ -10,6 +12,28 @@ import { buildStageEnvironment, isAmbientBlockedEnv, isForeverDeniedSecret, } fr
 import { ensureStageCacheDirs } from "./stageCacheEnv.js";
 import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
+function defaultStageCliEntry() {
+    const source = import.meta.url.split("?")[0]?.endsWith(".ts") === true;
+    return fileURLToPath(new URL(source ? "../cli.ts" : "../cli.js", import.meta.url));
+}
+function isTypeScriptEntry(entry) {
+    return /\.(?:m|c)?ts$/.test(entry);
+}
+/**
+ * A compiled `dist/cli.js` child is plain node. `npm run dev` is TypeScript,
+ * and this launcher sets execArgv explicitly so the parent's tsx loader is
+ * not inherited. Load that entry with the same tsx hooks the dev CLI uses.
+ */
+function tsxLoaderExecArgv() {
+    try {
+        const preflight = fileURLToPath(import.meta.resolve("tsx/preflight"));
+        const loader = import.meta.resolve("tsx");
+        return ["--require", preflight, "--import", loader];
+    }
+    catch {
+        return [];
+    }
+}
 function flushCappedPartial(log, event, text, maxLineBytes) {
     let remaining = redactString(text, { namedSecrets: getNamedSecrets() });
     while (Buffer.byteLength(remaining, "utf8") > maxLineBytes) {
@@ -109,6 +133,7 @@ export class StageProcessLauncher {
     env;
     explicitChildExtras;
     cliEntry;
+    workerExecArgv;
     logger;
     forkFn;
     active = new Map();
@@ -126,9 +151,11 @@ export class StageProcessLauncher {
                 : undefined;
         this.maxActive = readMaxActiveStageProcesses(this.env, options.maxActiveStageProcesses);
         this.heapMb = getContainerLimits().maxOldSpaceSizeMb;
-        this.cliEntry =
-            options.cliEntry ??
-                fileURLToPath(new URL("../cli.js", import.meta.url));
+        this.cliEntry = options.cliEntry ?? defaultStageCliEntry();
+        this.workerExecArgv = [
+            `--max-old-space-size=${this.heapMb}`,
+            ...(isTypeScriptEntry(this.cliEntry) ? tsxLoaderExecArgv() : []),
+        ];
         this.logger =
             options.logger ?? rootLogger.child({ component: "runtime" });
         this.forkFn = options.forkFn ?? childProcess.fork;
@@ -290,6 +317,7 @@ export class StageProcessLauncher {
             cacheVars: ensureStageCacheDirs(),
             grants: input.grants,
             attemptHome: input.attemptHome,
+            runVars: input.browserEnv,
             packageVersion: PACKAGE_VERSION,
         });
         for (const warning of built.warnings) {
@@ -301,14 +329,25 @@ export class StageProcessLauncher {
         const withExtras = this.explicitChildExtras !== undefined
             ? { ...built.env, ...this.explicitChildExtras }
             : built.env;
-        const childEnv = overlayStageBindingEnv(withExtras, input.env ?? {}, input.bindingKind ?? "unbound");
+        const overlaid = overlayStageBindingEnv(withExtras, input.env ?? {}, input.bindingKind ?? "unbound");
+        const withBrowser = input.browserEnv !== undefined
+            ? {
+                ...Object.fromEntries(Object.entries(overlaid).filter(([name]) => !name.startsWith(BROWSER_ENV_PREFIX))),
+                ...input.browserEnv,
+            }
+            : overlaid;
+        const childEnv = {
+            ...withBrowser,
+            [PI_HOME_AUTH_PATH_ENV]: piHomeAuthPath(),
+        };
         const child = this.forkFn(this.cliEntry, args, {
             cwd: input.rootDir,
             env: { ...childEnv, [SF_STAGE_WORKER]: "1" },
             stdio: ["pipe", "pipe", "pipe", "ipc"],
             detached: true,
             // Explicit: do not inherit Host execArgv; set heap from cgroup budget.
-            execArgv: [`--max-old-space-size=${this.heapMb}`],
+            // TypeScript entries also get the tsx loader, since that inheritance is off.
+            execArgv: this.workerExecArgv,
         });
         const key = activeKey(input.runId, input.stageId);
         const tracked = {

package/dist/runtime/stageRunner.d.ts

@@ -1,4 +1,6 @@
 import type { AgentPort, FeedbackLoopContext, StageHandle, StageRunResult, StageSessionMode } from "../agent/port.js";
+import { type HostGateContext } from "../browser/gateHandoff.js";
+import type { StageBrowserSupport } from "../browser/browserHost.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { LoadedStageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
@@ -49,6 +51,8 @@ export type RunStageOptions = {
     feedbackLoopContext?: FeedbackLoopContext;
     resumeToken?: string;
     stageEnv?: Record<string, string>;
+    /** Test seam for the Host login check run by a `browser_login` verify item. */
+    browser?: Pick<StageBrowserSupport, "runner" | "loginCheck">;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).
@@ -62,5 +66,6 @@ export declare function runStageYieldLoop(options: {
     store?: RunStore;
     attemptCtx?: StageAttemptContext;
     skipGates?: boolean;
+    gateContext?: HostGateContext;
 }): Promise<RunStageYieldLoopResult>;
 export declare function runStage(options: RunStageOptions): Promise<RunStageOutcome>;

package/dist/runtime/stageRunner.js

@@ -1,8 +1,11 @@
+import { hostGateContextFor, stampGateRequest, } from "../browser/gateHandoff.js";
 import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
 import { buildStageRoots, withResolvedAuthPath, } from "./stageRoots.js";
 import { createDefaultHitlQaHooks, recordWaitEnter, } from "./stageHitl.js";
 import { openStageAttempt, } from "./stageAttemptBootstrap.js";
 import { createVerifiedStageExecution } from "./verifiedStageExecution.js";
+import { BROWSER_STAGE_PATTERNS, redact } from "../logging/redact.js";
+import { getNamedSecrets } from "../logging/namedSecrets.js";
 import { isStageTimeoutReason } from "../agent/stageTimeout.js";
 export function isRunStageWaiting(outcome) {
     return "waiting" in outcome && outcome.waiting === true;
@@ -44,11 +47,16 @@ async function appendLifecycleEventAndPatchExecution(options) {
     }
 }
 async function finalizeStageResult(options) {
-    const { store, runId, stageId, result, activityChain, attemptCtx } = options;
+    const { store, runId, stageId, result, activityChain, attemptCtx, browser } = options;
     const attemptOpt = attemptCtx?.eventOptions();
     await activityChain;
     if (result.envelope) {
-        await store.writeEnvelope(runId, stageId, result.envelope, attemptOpt);
+        await store.writeEnvelope(runId, stageId, browser
+            ? redact(result.envelope, {
+                patterns: BROWSER_STAGE_PATTERNS,
+                namedSecrets: getNamedSecrets(),
+            })
+            : result.envelope, attemptOpt);
     }
     if (!result.ok) {
         await appendLifecycleEventAndPatchExecution({
@@ -75,10 +83,11 @@ async function finalizeStageResult(options) {
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).
  */
 export async function runStageYieldLoop(options) {
-    const { handle, runId, stageId, hitl, workerMode, store, attemptCtx, skipGates } = options;
+    const { handle, runId, stageId, hitl, workerMode, store, attemptCtx, skipGates, gateContext } = options;
     while (true) {
         const event = await handle.next();
         if (event.status === "waiting_for_input") {
+            const request = stampGateRequest(event.request, gateContext);
             if (skipGates) {
                 return {
                     ok: false,
@@ -96,7 +105,7 @@ export async function runStageYieldLoop(options) {
                     store,
                     runId,
                     stageId,
-                    request: event.request,
+                    request,
                     attemptCtx,
                     qaHooks: createDefaultHitlQaHooks(store),
                 });
@@ -108,14 +117,14 @@ export async function runStageYieldLoop(options) {
                     reason: "stage requested wait but no HITL controller is configured",
                 };
             }
-            await hitl.enterWait(runId, stageId, handle, event.request, attemptCtx);
+            await hitl.enterWait(runId, stageId, handle, request, attemptCtx);
             continue;
         }
         return event.result;
     }
 }
 export async function runStage(options) {
-    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, } = options;
+    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, } = options;
     const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
@@ -144,6 +153,19 @@ export async function runStage(options) {
         dag,
         roots,
         commandEnv: stageEnv ?? process.env,
+        ...(stage.browser?.check !== undefined
+            ? {
+                browserLogin: {
+                    check: stage.browser.check,
+                    ...(browserSeams?.runner !== undefined
+                        ? { runner: browserSeams.runner }
+                        : {}),
+                    ...(browserSeams?.loginCheck !== undefined
+                        ? { options: browserSeams.loginCheck }
+                        : {}),
+                },
+            }
+            : {}),
     });
     await verifiedExecution.prepare();
     console.error(`Running stage ${stageId} (${stage.model})...`);
@@ -209,6 +231,7 @@ export async function runStage(options) {
             store: workerMode ? store : undefined,
             attemptCtx,
             skipGates,
+            gateContext: hostGateContextFor(stage.browser),
         });
     }
     catch (err) {
@@ -253,6 +276,7 @@ export async function runStage(options) {
             result,
             activityChain,
             attemptCtx,
+            browser: stage.browser !== undefined,
         });
     }
     finally {

package/dist/runtime/stageStreamLog.d.ts

@@ -14,4 +14,5 @@ export type StageStreamLogWriter = {
 export declare function createStageStreamLogWriter(streamLogPath: string, options?: {
     flushThrottleMs?: number;
     capBytes?: number;
+    redact?: (text: string) => string;
 }): StageStreamLogWriter;

package/dist/runtime/stageStreamLog.js

@@ -54,6 +54,7 @@ async function appendChunk(streamLogPath, chunk, capBytes) {
 export function createStageStreamLogWriter(streamLogPath, options = {}) {
     const flushThrottleMs = options.flushThrottleMs ?? STREAM_FLUSH_THROTTLE_MS;
     const capBytes = options.capBytes ?? DEFAULT_CAP_BYTES;
+    const scrub = options.redact ?? redactSecrets;
     let buffer = "";
     let timer = null;
     // Serializes disk writes so the throttle timer and an eager flush() never race.
@@ -65,7 +66,7 @@ export function createStageStreamLogWriter(streamLogPath, options = {}) {
         }
         if (!buffer)
             return writeChain;
-        const chunk = redactSecrets(buffer);
+        const chunk = scrub(buffer);
         buffer = "";
         writeChain = writeChain.then(() => appendChunk(streamLogPath, chunk, capBytes));
         return writeChain;

package/dist/runtime/triggerCatalog.d.ts

@@ -0,0 +1,6 @@
+import type { TriggerFile } from "../types/trigger.js";
+export declare function findCatalogPathById(paths: string[], id: string): Promise<string | undefined>;
+export declare function findTriggerDefinition(triggerPaths: string[], triggerId: string): Promise<{
+    path: string;
+    definition: TriggerFile;
+} | undefined>;

package/dist/runtime/triggerCatalog.js

@@ -0,0 +1,24 @@
+import { readYamlObject } from "../config/readYamlObject.js";
+import { loadTriggerOutcome } from "../config/loadTrigger.js";
+export async function findCatalogPathById(paths, id) {
+    for (const filePath of paths) {
+        try {
+            const raw = await readYamlObject(filePath);
+            if (raw?.id === id)
+                return filePath;
+        }
+        catch {
+            // Unreadable/invalid catalog files are surfaced by `sf validate`; skip here.
+        }
+    }
+    return undefined;
+}
+export async function findTriggerDefinition(triggerPaths, triggerId) {
+    for (const filePath of triggerPaths) {
+        const outcome = await loadTriggerOutcome(filePath);
+        if (outcome.ok && outcome.value.id === triggerId) {
+            return { path: filePath, definition: outcome.value };
+        }
+    }
+    return undefined;
+}

package/dist/runtime/triggerEventMatch.d.ts

@@ -0,0 +1,2 @@
+/** Subset-match: every key/value in `match` must equal-match `payload`. No `match` matches everything. */
+export declare function matchesEventFilter(match: Record<string, unknown> | undefined, payload: Record<string, unknown>): boolean;

package/dist/runtime/triggerEventMatch.js

@@ -0,0 +1,6 @@
+/** Subset-match: every key/value in `match` must equal-match `payload`. No `match` matches everything. */
+export function matchesEventFilter(match, payload) {
+    if (!match)
+        return true;
+    return Object.entries(match).every(([key, value]) => payload[key] === value);
+}

package/dist/runtime/triggerPort.d.ts

@@ -0,0 +1,14 @@
+import type { TaskFile } from "../types/task.js";
+export type TriggerFireEvent = {
+    triggerId: string;
+    task?: TaskFile;
+};
+/**
+ * Abstract seam for anything that decides "fire trigger X now" — a croner-backed
+ * schedule loop, a GitHub/email poller, a webhook receiver. No adapter implements
+ * this yet; it exists so those later adapters build against a locked contract.
+ */
+export interface TriggerSourcePort {
+    start(onFire: (event: TriggerFireEvent) => Promise<void>): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/runtime/triggerPort.js

@@ -0,0 +1 @@
+export {};

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);
+}