stageflow 0.27.0 → 0.31.0

package/dist/server/requestAuthContext.d.ts

@@ -1,5 +1,5 @@
 import type { BearerAuth, ControlScope } from "./controlToken.js";
-export type CallerSurface = "mcp" | "rest" | "cli" | "a2a";
+export type CallerSurface = "mcp" | "rest" | "cli" | "a2a" | "webhook";
 export type RequestAuthContext = {
     scope: ControlScope;
     caller_id: string;

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>;

package/dist/server/triggerRoutes.js

@@ -0,0 +1,268 @@
+import { fireTrigger } from "../runtime/triggerRunner.js";
+import { findTriggerDefinition } from "../runtime/triggerCatalog.js";
+import { matchesEventFilter } from "../runtime/triggerEventMatch.js";
+import { verifyHmacSignature } from "../runtime/webhookSignature.js";
+import { mapStartFailure } from "./operatorResults.js";
+import { writeAudit } from "../logging/audit.js";
+import { callerIdFromRequestAuth, getRequestAuth, } from "./requestAuthContext.js";
+import { loadCatalogTriggers } from "../config/triggerCatalog.js";
+import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
+import { CatalogPathError, catalogPathErrorBody, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
+import { resolveStageflowContext } from "../project/resolveStageflowContext.js";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
+import { getCatalogScanPaths } from "../config/browseCatalog.js";
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { coerceTaskFile } from "../config/loadTask.js";
+export async function handleTriggerRoutes(req, res, ctx) {
+    const { cwd, manager, store, json, readJsonBody, readRawBody, auditLog } = ctx;
+    const method = req.method ?? "GET";
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (method === "POST" && pathname === "/api/triggers") {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        const writeRoot = body !== null &&
+            typeof body === "object" &&
+            !Array.isArray(body) &&
+            typeof body.project_root === "string"
+            ? body.project_root
+            : undefined;
+        let triggerWriteRoot;
+        try {
+            const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
+            triggerWriteRoot = selected.path;
+        }
+        catch (err) {
+            if (err instanceof CatalogPathError) {
+                json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                return true;
+            }
+            throw err;
+        }
+        const parsed = parseCreateTriggerBody(body);
+        if ("ok" in parsed) {
+            json(res, parsed.status, { error: parsed.error });
+            return true;
+        }
+        const stageflowCtx = await resolveStageflowContext(triggerWriteRoot);
+        if (stageflowCtx.manifestStatus !== "ok") {
+            json(res, 400, {
+                error: "Project root not found; initialize stageflow.yaml",
+            });
+            return true;
+        }
+        const callerId = callerIdFromRequestAuth();
+        const result = await createTrigger(stageflowCtx.projectRoot, parsed);
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_create",
+                outcome: "error",
+            });
+            json(res, result.status, { error: result.error });
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_create",
+            outcome: "ok",
+        });
+        json(res, 201, result.trigger);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/triggers") {
+        const items = await loadCatalogTriggers(cwd, store);
+        if (items === undefined) {
+            json(res, 404, { error: "No Stageflow catalog found" });
+            return true;
+        }
+        json(res, 200, { triggers: items });
+        return true;
+    }
+    const fireMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/fire$/);
+    if (method === "POST" && fireMatch) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            // empty/invalid body ok
+        }
+        const rawTask = body !== null && typeof body === "object" && !Array.isArray(body)
+            ? body.task
+            : undefined;
+        let task;
+        if (rawTask !== undefined) {
+            task = coerceTaskFile(rawTask);
+            if (task === undefined) {
+                json(res, 400, { error: "Invalid task: id and goal are required strings" });
+                return true;
+            }
+        }
+        const id = decodeURIComponent(fireMatch[1] ?? "");
+        const callerId = callerIdFromRequestAuth();
+        const result = await fireTrigger(id, store, manager, { cwd, task });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_fire",
+                outcome: "error",
+                error_code: result.code,
+            });
+            json(res, result.status ?? 500, mapStartFailure(result));
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_fire",
+            target_run_id: result.runId,
+            outcome: "ok",
+        });
+        json(res, 202, {
+            runId: result.runId,
+            ...(result.queued === true
+                ? {
+                    queued: true,
+                    queuePosition: result.queuePosition,
+                    ...(result.queuedCode !== undefined
+                        ? { queuedCode: result.queuedCode }
+                        : {}),
+                }
+                : {}),
+        });
+        return true;
+    }
+    const webhookMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/webhook$/);
+    if (method === "POST" && webhookMatch) {
+        const id = decodeURIComponent(webhookMatch[1] ?? "");
+        const callerId = callerIdFromRequestAuth();
+        const catalogCtx = catalogContextFromStageflow(await resolveStageflowContext(cwd));
+        const scanPaths = await getCatalogScanPaths(catalogCtx);
+        const found = scanPaths
+            ? await findTriggerDefinition(scanPaths.triggerPaths, id)
+            : undefined;
+        if (!found) {
+            json(res, 404, { error: `Trigger not found: ${id}` });
+            return true;
+        }
+        const { definition: trigger } = found;
+        const config = trigger.event?.config;
+        const secretRef = typeof config?.secretRef === "string" ? config.secretRef : undefined;
+        const header = typeof config?.header === "string" ? config.header : undefined;
+        if (secretRef === undefined || header === undefined) {
+            json(res, 400, { error: "this trigger has no webhook signing configured" });
+            return true;
+        }
+        const scheme = config?.scheme === "base64" ? "base64" : "hex";
+        let secret;
+        try {
+            secret = readSecretFromEnvOrFile(process.env, secretRef);
+        }
+        catch {
+            secret = undefined;
+        }
+        if (secret === undefined) {
+            json(res, 400, { error: "this trigger has no webhook signing configured" });
+            return true;
+        }
+        const rawBody = await readRawBody(req);
+        const headerValue = req.headers[header.toLowerCase()];
+        const signature = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+        if (typeof signature !== "string" ||
+            signature.length === 0 ||
+            !verifyHmacSignature(rawBody, signature, secret, scheme)) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: "webhook",
+                action: "trigger_webhook",
+                outcome: "error",
+                error_code: "webhook.signature_invalid",
+            });
+            json(res, 401, { error: "Invalid webhook signature" });
+            return true;
+        }
+        let payload;
+        try {
+            payload = rawBody.length === 0 ? {} : JSON.parse(rawBody.toString("utf8"));
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+            json(res, 400, { error: "Invalid JSON body: expected an object" });
+            return true;
+        }
+        const payloadRecord = payload;
+        if (!matchesEventFilter(trigger.event?.match, payloadRecord)) {
+            json(res, 200, { fired: false });
+            return true;
+        }
+        const task = trigger.task === undefined
+            ? {
+                id: `${id}-webhook-${Date.now()}`,
+                goal: `Handle webhook event for trigger "${id}"`,
+                input: payloadRecord,
+            }
+            : undefined;
+        const result = await fireTrigger(id, store, manager, { cwd, task });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: "webhook",
+                action: "trigger_webhook",
+                outcome: "error",
+                error_code: result.code,
+            });
+            json(res, result.status ?? 500, mapStartFailure(result));
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: "webhook",
+            action: "trigger_webhook",
+            target_run_id: result.runId,
+            outcome: "ok",
+        });
+        json(res, 201, {
+            fired: true,
+            runId: result.runId,
+            ...(result.queued === true
+                ? {
+                    queued: true,
+                    queuePosition: result.queuePosition,
+                    ...(result.queuedCode !== undefined
+                        ? { queuedCode: result.queuedCode }
+                        : {}),
+                }
+                : {}),
+        });
+        return true;
+    }
+    const idMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
+    if (method === "GET" && idMatch) {
+        const id = decodeURIComponent(idMatch[1] ?? "");
+        const items = await loadCatalogTriggers(cwd, store);
+        if (items === undefined) {
+            json(res, 404, { error: "No Stageflow catalog found" });
+            return true;
+        }
+        const found = items.find((item) => item.id === id);
+        if (!found) {
+            json(res, 404, { error: `Trigger not found: ${id}` });
+            return true;
+        }
+        json(res, 200, found);
+        return true;
+    }
+    return false;
+}

package/dist/tools/askOperator.d.ts

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import type { HostGateContext } from "../browser/gateHandoff.js";
 export declare class AskOperatorError extends Error {
     constructor(message: string);
 }
@@ -37,7 +38,7 @@ export type MultiQuestionItem = {
     message: string;
     id: string;
 };
-export type AskOperatorPrompt = {
+export type AskOperatorPrompt = ({
     kind: "free_text";
     message: string;
     id: string;
@@ -54,7 +55,7 @@ export type AskOperatorPrompt = {
     message: string;
     artifacts: string[];
     id: string;
-};
+}) & HostGateContext;
 export type Decision = "accept" | "reject";
 export type FreeTextAnswerPayload = {
     kind: "free_text";

package/dist/types/completion.d.ts

@@ -31,6 +31,9 @@ export type CompletionCheck = {
     id: string;
     type: "checkout_changes";
     path_fields?: string[];
+} | {
+    id: string;
+    type: "browser_login";
 };
 export type CompletionContract = {
     mode: "all";

package/dist/types/pipeline.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedStageConfig, StageGateKind, StageIoYaml } from "./stage.js";
+import type { LoadedStageConfig, StageBrowserConfig, StageGateKind, StageIoYaml } from "./stage.js";
 import type { CompletionContract, RecoveryPolicy } from "./completion.js";
 import type { StageSecretDecl } from "../runtime/stageSecretDecl.js";
 import type { ToolRequirement } from "../config/toolRequires.js";
@@ -134,6 +134,7 @@ export type PipelineStageYamlEntry = {
     timeout_ms?: number;
     skill?: string;
     mcp?: string[];
+    browser?: StageBrowserConfig;
     replay_safe?: boolean;
     route?: PipelineRouteEntry[];
     entry?: boolean;
@@ -162,6 +163,7 @@ export type NormalizedPipelineStageEntry = {
     mcp?: string[];
     secrets?: StageSecretDecl[];
     requires?: ToolRequirement[];
+    browser?: StageBrowserConfig;
     clone_cap?: number;
     clone_mode?: CloneMode;
     body: {

package/dist/types/preEmitCheck.d.ts

@@ -13,4 +13,11 @@ export type PreEmitCheck = {
     id: string;
     type: "artifact_declared";
     basename: string;
+} | {
+    /** Host-injected for `browser.check` stages; never authored in YAML. */
+    id: string;
+    type: "browser_login_check";
+    state: "logged_in" | "logged_out" | "unknown";
+    logged_in: boolean | null;
+    url: string;
 };

package/dist/types/stage.d.ts

@@ -24,6 +24,18 @@ export type StageIoYaml = {
  * in `src/config/yamlDialect.ts`. Do not add new catalog keys here — add them on
  * the YAML dialect and map them in compileTargetContract.
  */
+export type StageBrowserConfig = {
+    profile?: string;
+    headed?: boolean;
+    allow_domains?: string[];
+    /** Page the Host opens for a human login stage; defaults to `check.url`. */
+    login_url?: string;
+    check?: {
+        url: string;
+        logged_in_url?: string;
+        logged_out_url?: string | string[];
+    };
+};
 export type StageConfig = {
     id: string;
     system_prompt: string;
@@ -44,6 +56,8 @@ export type StageConfig = {
     secrets?: StageSecretDecl[];
     /** Declared toolchain binaries this stage needs (Slot 9). */
     requires?: ToolRequirement[];
+    /** Browser session settings for this stage; adds the agent-browser requirement. */
+    browser?: StageBrowserConfig;
     /**
      * Selects the AgentPort backend for this stage, overriding pipeline/global.
      * Parsed but not yet consulted — see STAGE_LEVEL_AGENT_OVERRIDE_ENABLED.

package/dist/types/stageflowManifest.d.ts

@@ -2,9 +2,11 @@ export type StageflowManifestVersion = 1;
 export type StageflowManifestCatalog = {
     pipelines: string[];
     tasks: string[];
+    triggers?: string[];
     patterns?: {
         pipeline?: string;
         task?: string;
+        trigger?: string;
     };
     exclude?: string[];
 };
@@ -23,5 +25,6 @@ export type LoadedManifest = {
     patterns: {
         pipeline: string;
         task: string;
+        trigger: string;
     };
 };

package/dist/types/trigger.d.ts

@@ -0,0 +1,18 @@
+export type TriggerSchedule = {
+    cron: string;
+    timezone?: string;
+};
+export type TriggerEvent = {
+    source: string;
+    match?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+};
+export type TriggerFile = {
+    id: string;
+    pipeline: string;
+    task?: string;
+    kind: "manual" | "schedule" | "event";
+    schedule?: TriggerSchedule;
+    event?: TriggerEvent;
+    enabled: boolean;
+};

package/dist/types/trigger.js

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