stageflow 0.33.0 → 0.36.0

package/dist/server/readCatalogFile.d.ts

@@ -0,0 +1,29 @@
+import { type ResolveCatalogRelativePathInput } from "../config/catalogRelativePath.js";
+import { type ValidationFinding } from "../config/validateCatalog.js";
+export declare const CATALOG_FILE_MAX_BYTES: number;
+export type CatalogFileReadErrorCode = "unsupported_file_type" | "path_outside_project_root" | "catalog_file_not_found" | "catalog_file_too_large";
+export type ReadCatalogFileResult = {
+    ok: true;
+    path: string;
+    content: string;
+} | {
+    ok: false;
+    status: 400 | 404 | 413;
+    error: string;
+    code: CatalogFileReadErrorCode;
+};
+export type WriteCatalogFileResult = {
+    ok: true;
+    path: string;
+    content: string;
+} | {
+    ok: false;
+    status: 400 | 404 | 413;
+    error: string;
+    code: CatalogFileReadErrorCode | "stage_invalid";
+    findings?: ValidationFinding[];
+};
+export declare function readCatalogFileForHttp(input: ResolveCatalogRelativePathInput): Promise<ReadCatalogFileResult>;
+export declare function writeCatalogFileForHttp(input: ResolveCatalogRelativePathInput & {
+    content: string;
+}): Promise<WriteCatalogFileResult>;

package/dist/server/readCatalogFile.js

@@ -0,0 +1,215 @@
+import { readFile, realpath, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CatalogPathError, isInsideProjectRoot, resolveCatalogRelativePath, } from "../config/catalogRelativePath.js";
+import { loadStageOutcome } from "../config/loadStage.js";
+import { findingsFromLoadIssues, } from "../config/validateCatalog.js";
+export const CATALOG_FILE_MAX_BYTES = 512 * 1024;
+function isCatalogYamlExtension(inputPath) {
+    const ext = path.extname(inputPath).toLowerCase();
+    return ext === ".yaml" || ext === ".yml";
+}
+export async function readCatalogFileForHttp(input) {
+    if (!isCatalogYamlExtension(input.inputPath)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    let resolved;
+    try {
+        resolved = resolveCatalogRelativePath(input);
+    }
+    catch (err) {
+        if (err instanceof CatalogPathError) {
+            if (err.code === "path_outside_project_root") {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: err.message,
+                    code: "path_outside_project_root",
+                };
+            }
+            throw err;
+        }
+        throw err;
+    }
+    let rootReal;
+    let fileReal;
+    try {
+        rootReal = await realpath(resolved.root.path);
+        fileReal = await realpath(resolved.absolutePath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!isInsideProjectRoot(rootReal, fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: `path escapes project_root ${resolved.root.project_root}`,
+            code: "path_outside_project_root",
+        };
+    }
+    if (!isCatalogYamlExtension(fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(fileReal);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!fileStat.isFile()) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be read",
+            code: "unsupported_file_type",
+        };
+    }
+    if (fileStat.size > CATALOG_FILE_MAX_BYTES) {
+        return {
+            ok: false,
+            status: 413,
+            error: `Catalog file exceeds ${CATALOG_FILE_MAX_BYTES} byte limit`,
+            code: "catalog_file_too_large",
+        };
+    }
+    const content = await readFile(fileReal, "utf8");
+    return { ok: true, path: resolved.relativePath, content };
+}
+export async function writeCatalogFileForHttp(input) {
+    if (!isCatalogYamlExtension(input.inputPath)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    if (Buffer.byteLength(input.content, "utf8") > CATALOG_FILE_MAX_BYTES) {
+        return {
+            ok: false,
+            status: 413,
+            error: `Catalog file exceeds ${CATALOG_FILE_MAX_BYTES} byte limit`,
+            code: "catalog_file_too_large",
+        };
+    }
+    let resolved;
+    try {
+        resolved = resolveCatalogRelativePath(input);
+    }
+    catch (err) {
+        if (err instanceof CatalogPathError) {
+            if (err.code === "path_outside_project_root") {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: err.message,
+                    code: "path_outside_project_root",
+                };
+            }
+            throw err;
+        }
+        throw err;
+    }
+    let rootReal;
+    let fileReal;
+    try {
+        rootReal = await realpath(resolved.root.path);
+        fileReal = await realpath(resolved.absolutePath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!isInsideProjectRoot(rootReal, fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: `path escapes project_root ${resolved.root.project_root}`,
+            code: "path_outside_project_root",
+        };
+    }
+    if (!isCatalogYamlExtension(fileReal)) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    let fileStat;
+    try {
+        fileStat = await stat(fileReal);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            return {
+                ok: false,
+                status: 404,
+                error: "Catalog file not found",
+                code: "catalog_file_not_found",
+            };
+        }
+        throw err;
+    }
+    if (!fileStat.isFile()) {
+        return {
+            ok: false,
+            status: 400,
+            error: "Only .yaml and .yml catalog files can be written",
+            code: "unsupported_file_type",
+        };
+    }
+    const original = await readFile(fileReal, "utf8");
+    await writeFile(fileReal, input.content, "utf8");
+    const outcome = await loadStageOutcome(fileReal);
+    if (!outcome.ok) {
+        await writeFile(fileReal, original, "utf8");
+        const findings = findingsFromLoadIssues(resolved.root.path, fileReal, outcome.issues);
+        return {
+            ok: false,
+            status: 400,
+            error: findings[0]?.message ?? "Invalid stage YAML",
+            code: "stage_invalid",
+            findings,
+        };
+    }
+    return { ok: true, path: resolved.relativePath, content: input.content };
+}

package/dist/server/triggerRoutes.d.ts

@@ -3,6 +3,7 @@ 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 { TriggerAdapterStatus } from "../config/triggerAdapterStatus.js";
 export type TriggerRoutesCtx = {
     cwd: string;
     manager: RunManager;

package/dist/server/triggerRoutes.js

@@ -1,18 +1,40 @@
 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 { acceptWebhook } from "../runtime/webhookAccept.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 { findCatalogTrigger, loadCatalogTriggers, triggerStoreId, } from "../config/triggerCatalog.js";
 import { createTrigger, parseCreateTriggerBody } from "../config/createTrigger.js";
+import { parsePatchTriggerBody, parsePutTriggerBody, updateTriggerDefinition, updateTriggerEnabled, projectRootFilterFromBody, } from "../config/updateTrigger.js";
+import { readTriggerAdapterStatus, } from "../config/triggerAdapterStatus.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";
+async function enrichTriggerListItem(item, store) {
+    const adapter_status = await readTriggerAdapterStatus(item, store);
+    return { ...item, adapter_status };
+}
+function resolveListedTrigger(items, id, projectRootWire) {
+    if (projectRootWire) {
+        const found = items.find((item) => item.id === id && item.project_root === projectRootWire);
+        if (!found) {
+            return { error: `Trigger not found: ${id}`, status: 404 };
+        }
+        return found;
+    }
+    const matches = items.filter((item) => item.id === id);
+    if (matches.length === 0) {
+        return { error: `Trigger not found: ${id}`, status: 404 };
+    }
+    if (matches.length > 1) {
+        return {
+            error: `Trigger id is ambiguous across catalog roots: ${id}`,
+            status: 409,
+            project_roots: [...new Set(matches.map((m) => m.project_root))].sort((a, b) => a.localeCompare(b)),
+        };
+    }
+    return matches[0];
+}
 export async function handleTriggerRoutes(req, res, ctx) {
     const { cwd, manager, store, json, readJsonBody, readRawBody, auditLog } = ctx;
     const method = req.method ?? "GET";
@@ -78,12 +100,9 @@ export async function handleTriggerRoutes(req, res, ctx) {
         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 });
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const triggers = await Promise.all(items.map((item) => enrichTriggerListItem(item, store)));
+        json(res, 200, { triggers });
         return true;
     }
     const fireMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/fire$/);
@@ -107,8 +126,14 @@ export async function handleTriggerRoutes(req, res, ctx) {
             }
         }
         const id = decodeURIComponent(fireMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
         const callerId = callerIdFromRequestAuth();
-        const result = await fireTrigger(id, store, manager, { cwd, task });
+        const result = await fireTrigger(id, store, manager, {
+            cwd,
+            task,
+            ...(projectRootWire ? { project_root: projectRootWire } : {}),
+        });
         if (!result.ok) {
             writeAudit(auditLog, {
                 caller_id: callerId,
@@ -145,41 +170,45 @@ export async function handleTriggerRoutes(req, res, ctx) {
     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" });
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const located = await findCatalogTrigger({
+            store,
+            bootCwd: cwd,
+            triggerId: id,
+            ...(projectRootWire ? { projectRootFilter: projectRootWire } : {}),
+        });
+        if (!located.ok) {
+            if (located.status === 409 && located.code === "ambiguous_trigger") {
+                json(res, located.status, {
+                    error: located.reason,
+                    code: located.code,
+                    project_roots: located.project_roots,
+                });
+            }
+            else if (located.status === 400 && located.code === "unknown_project_root") {
+                json(res, located.status, {
+                    error: located.reason,
+                    code: located.code,
+                });
+            }
+            else {
+                json(res, located.status, { error: located.reason });
+            }
             return true;
         }
-        const scheme = config?.scheme === "base64" ? "base64" : "hex";
-        let secret;
-        try {
-            secret = readSecretFromEnvOrFile(process.env, secretRef);
-        }
-        catch {
-            secret = undefined;
-        }
-        if (secret === undefined) {
+        const rawBody = await readRawBody(req);
+        const accepted = acceptWebhook({
+            trigger: located.match.definition,
+            rawBody,
+            headers: req.headers,
+            env: process.env,
+        });
+        if (accepted.kind === "not_configured") {
             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)) {
+        if (accepted.kind === "bad_signature") {
             writeAudit(auditLog, {
                 caller_id: callerId,
                 surface: "webhook",
@@ -190,31 +219,19 @@ export async function handleTriggerRoutes(req, res, ctx) {
             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" });
+        if (accepted.kind === "bad_json") {
+            json(res, 400, { error: accepted.error });
             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)) {
+        if (accepted.kind === "no_match") {
             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 });
+        const result = await fireTrigger(id, store, manager, {
+            cwd,
+            task: accepted.task,
+            project_root: located.match.project_root,
+        });
         if (!result.ok) {
             writeAudit(auditLog, {
                 caller_id: callerId,
@@ -248,20 +265,130 @@ export async function handleTriggerRoutes(req, res, ctx) {
         });
         return true;
     }
+    const statusMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/status$/);
+    if (method === "GET" && statusMatch) {
+        const id = decodeURIComponent(statusMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
+            return true;
+        }
+        const adapter_status = await readTriggerAdapterStatus(found, store);
+        json(res, 200, adapter_status);
+        return true;
+    }
+    const firesMatch = pathname.match(/^\/api\/triggers\/([^/]+)\/fires$/);
+    if (method === "GET" && firesMatch) {
+        const id = decodeURIComponent(firesMatch[1] ?? "");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
+            return true;
+        }
+        const fires = await store.listTriggerFires(triggerStoreId(found.project_root, found.id), 20);
+        json(res, 200, { fires });
+        return true;
+    }
+    const putMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
+    if (method === "PUT" && putMatch) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        const id = decodeURIComponent(putMatch[1] ?? "");
+        const parsed = parsePutTriggerBody(body, id);
+        if ("ok" in parsed) {
+            json(res, parsed.status, { error: parsed.error });
+            return true;
+        }
+        const projectRootFilter = projectRootFilterFromBody(body);
+        const callerId = callerIdFromRequestAuth();
+        const result = await updateTriggerDefinition(cwd, store, id, parsed, {
+            projectRootFilter,
+        });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_update",
+                outcome: "error",
+            });
+            json(res, result.status, { error: result.error });
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_update",
+            outcome: "ok",
+        });
+        const enriched = await enrichTriggerListItem(result.trigger, store);
+        json(res, 200, enriched);
+        return true;
+    }
+    const patchMatch = pathname.match(/^\/api\/triggers\/([^/]+)$/);
+    if (method === "PATCH" && patchMatch) {
+        let body;
+        try {
+            body = await readJsonBody(req);
+        }
+        catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return true;
+        }
+        const parsed = parsePatchTriggerBody(body);
+        if ("ok" in parsed) {
+            json(res, parsed.status, { error: parsed.error });
+            return true;
+        }
+        const id = decodeURIComponent(patchMatch[1] ?? "");
+        const projectRootFilter = projectRootFilterFromBody(body);
+        const callerId = callerIdFromRequestAuth();
+        const result = await updateTriggerEnabled(cwd, store, id, parsed.enabled, {
+            projectRootFilter,
+        });
+        if (!result.ok) {
+            writeAudit(auditLog, {
+                caller_id: callerId,
+                surface: getRequestAuth()?.surface ?? "rest",
+                action: "trigger_patch",
+                outcome: "error",
+            });
+            json(res, result.status, { error: result.error });
+            return true;
+        }
+        writeAudit(auditLog, {
+            caller_id: callerId,
+            surface: getRequestAuth()?.surface ?? "rest",
+            action: "trigger_patch",
+            outcome: "ok",
+        });
+        const enriched = await enrichTriggerListItem(result.trigger, store);
+        json(res, 200, enriched);
+        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}` });
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const projectRootWire = url.searchParams.get("project_root") ?? undefined;
+        const items = await loadCatalogTriggers({ store, bootCwd: cwd });
+        const found = resolveListedTrigger(items, id, projectRootWire);
+        if ("error" in found) {
+            json(res, found.status, { error: found.error, ...(found.project_roots ? { project_roots: found.project_roots } : {}) });
             return true;
         }
-        json(res, 200, found);
+        json(res, 200, await enrichTriggerListItem(found, store));
         return true;
     }
     return false;

package/dist/tools/sendMessage.d.ts

@@ -0,0 +1,21 @@
+import { Type } from "typebox";
+import { type StageChannels } from "../channels/host.js";
+export declare function createSendMessageTool(channels: StageChannels): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: Type.TObject<{
+        channel: Type.TOptional<Type.TString>;
+        text: Type.TString;
+        subject: Type.TOptional<Type.TString>;
+        operationKey: Type.TString;
+    }>;
+    execute(_toolCallId: string, input: unknown): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: unknown;
+        isError?: boolean;
+    }>;
+};

package/dist/tools/sendMessage.js

@@ -0,0 +1,25 @@
+import { Type } from "typebox";
+import { MAX_MESSAGE_TEXT, channelFault } from "../channels/host.js";
+export function createSendMessageTool(channels) {
+    return {
+        name: "send_message",
+        label: "Send message",
+        description: "Send a message on one of this stage's declared communication channels. The recipient is fixed by Stageflow configuration and cannot be chosen. Pass the channel alias when the stage declares more than one. Reuse the same operationKey when retrying the same message. Acceptance means provider submission, not delivery or that anyone read it. Never retry an unknown outcome with a new key. Do not put secrets in a message.",
+        parameters: Type.Object({
+            channel: Type.Optional(Type.String()),
+            text: Type.String({ maxLength: MAX_MESSAGE_TEXT }),
+            subject: Type.Optional(Type.String()),
+            operationKey: Type.String(),
+        }),
+        async execute(_toolCallId, input) {
+            try {
+                const receipt = await channels.send(input);
+                return { content: [{ type: "text", text: JSON.stringify(receipt) }], details: receipt };
+            }
+            catch (error) {
+                const details = channelFault(error);
+                return { content: [{ type: "text", text: JSON.stringify(details) }], details, isError: true };
+            }
+        },
+    };
+}

package/dist/tools/writeStageArtifact.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Custom Pi tool for writing factory stage artifact files under the run
+ * workspace. Paths are relative to
+ * `stages/<stageId>/attempts/<attempt>/artifacts/` and must resolve inside
+ * that directory.
+ *
+ * Parameter schemas use `typebox` (Pi's `defineTool` TSchema), not
+ * `@sinclair/typebox`. Unlike emit, this tool does not terminate the turn.
+ */
 import { Type } from "typebox";
 export type WriteStageArtifactOptions = {
     runWorkspaceDir: string;