stageflow 0.35.0 → 0.36.0

package/dist/runtime/stageProcessLauncher.js

@@ -13,6 +13,8 @@ import { buildStageEnvironment, isAmbientBlockedEnv, isForeverDeniedSecret, } fr
 import { ensureStageCacheDirs } from "./stageCacheEnv.js";
 import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
 import { emailHostFor, emailWorkerEnvironment, stageEmail, validateStageEmailAccounts } from "../email/host.js";
+import { ChannelError } from "../channels/errors.js";
+import { channelFault, channelHostFor, channelsWorkerEnvironment, stageChannels, validateStageChannelConnections } from "../channels/host.js";
 import { EmailError } from "../email/port.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
 function defaultStageCliEntry() {
@@ -189,6 +191,15 @@ export class StageProcessLauncher {
                 return { type: "failed", reason: error.code };
             throw error;
         }
+        try {
+            if (input.stage?.channels?.length)
+                validateStageChannelConnections(channelHostFor(input.factoryCwd ?? input.operatorCatalog?.cwd ?? input.rootDir), input.stage);
+        }
+        catch (error) {
+            if (error instanceof ChannelError)
+                return { type: "failed", reason: error.code };
+            throw error;
+        }
         input = { ...input, stage: input.stage ? structuredClone(input.stage) : undefined };
         const acquired = await this.waitForCapacity(input.runId);
         if (!acquired) {
@@ -363,7 +374,7 @@ export class StageProcessLauncher {
         }
         const child = this.forkFn(this.cliEntry, args, {
             cwd: input.rootDir,
-            env: emailWorkerEnvironment({ ...childEnv, [SF_STAGE_WORKER]: "1" }, emailHostFor(factoryCwd).accounts),
+            env: channelsWorkerEnvironment(emailWorkerEnvironment({ ...childEnv, [SF_STAGE_WORKER]: "1" }, emailHostFor(factoryCwd).accounts), factoryCwd),
             stdio: ["pipe", "pipe", "pipe", "ipc"],
             detached: true,
             // Explicit: do not inherit Host execArgv; set heap from cgroup budget.
@@ -432,6 +443,25 @@ export class StageProcessLauncher {
                     })();
                     return;
                 }
+                if (!settled && request?.type === "channel.send") {
+                    void (async () => {
+                        if (typeof request.requestId !== "string" || request.requestId.length > 100)
+                            return;
+                        let response;
+                        try {
+                            const stage = input.stage;
+                            if (!stage || settled)
+                                throw new ChannelError("CHANNEL_UNAUTHORIZED");
+                            response = { receipt: await stageChannels(channelHostFor(factoryCwd), stage, input.runId).send(request.input) };
+                        }
+                        catch (error) {
+                            response = { error: channelFault(error) };
+                        }
+                        if (child.connected && !settled)
+                            child.send({ type: "channel.response", requestId: request.requestId, ...response });
+                    })();
+                    return;
+                }
                 if (!isStageWorkerResult(message))
                     return;
                 finish(resultFromWorkerMessage(message));

package/dist/server/bootstrap.d.ts

@@ -9,6 +9,7 @@ import type { StageBrowserSupport } from "../browser/browserHost.js";
 import { RunManager } from "../runtime/runManager.js";
 import { emailHostFor } from "../email/host.js";
 import { EmailTriggers } from "../email/triggers.js";
+import { type ChannelService } from "../channels/service.js";
 import { type RunChangeBus } from "../runtime/runChangeBus.js";
 import { type McpHttpHandler } from "../mcp/server.js";
 import { type HostConfig } from "../config/hostConfig.js";
@@ -59,6 +60,8 @@ export type StageflowHostBootstrap = {
     stopGithubPollSource: () => void;
     /** Stops the email-trigger IMAP/IDLE listeners started at boot. */
     stopEmailSource: () => void;
+    /** Connections page read model and background health checks. */
+    channels?: ChannelService;
     email?: ReturnType<typeof emailHostFor> & {
         triggers: EmailTriggers;
         stop: () => Promise<void>;

package/dist/server/bootstrap.js

@@ -20,6 +20,7 @@ import { GithubPollSource, githubPollIntervalMsFromEnv, } from "../runtime/githu
 import { EmailSource } from "../runtime/emailSource.js";
 import { emailHostFor, releaseEmailHost } from "../email/host.js";
 import { EmailTriggers } from "../email/triggers.js";
+import { startChannelService } from "../channels/service.js";
 import { fireTrigger } from "../runtime/triggerRunner.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
@@ -331,9 +332,11 @@ export async function bootstrapStageflowHost(options) {
         await Promise.all([stopAccountEmail(), emailSource.stop(), scheduleSource.stop(), githubPollSource.stop()]);
         throw error;
     }
+    const channels = startChannelService(cwd);
     const stopEmailSource = () => {
         void emailSource.stop();
         void stopAccountEmail();
+        void channels.stop();
     };
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
@@ -374,6 +377,7 @@ export async function bootstrapStageflowHost(options) {
         stopGithubPollSource,
         stopEmailSource,
         email: { ...emailHost, triggers: emailTriggers, stop: stopAccountEmail },
+        channels,
         storeFilesystem,
         workspaceCatalog,
     };

package/dist/server/channelRoutes.d.ts

@@ -0,0 +1,9 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ChannelService } from "../channels/service.js";
+type Json = (res: ServerResponse, status: number, body: unknown) => void;
+/**
+ * Listing, live checks and edits. Request bodies carry secret values on the way in only; nothing
+ * the API returns contains one, and failures answer with a code, never the request or its values.
+ */
+export declare function handleChannelRoutes(req: IncomingMessage, method: string, pathname: string, service: ChannelService, res: ServerResponse, json: Json): Promise<boolean>;
+export {};

package/dist/server/channelRoutes.js

@@ -0,0 +1,88 @@
+import { ChannelError } from "../channels/errors.js";
+import { channelErrorStatus } from "../channels/errorInfo.js";
+const MAX_BODY_BYTES = 65536;
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buffer.length;
+        if (size > MAX_BODY_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        chunks.push(buffer);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+}
+/**
+ * Listing, live checks and edits. Request bodies carry secret values on the way in only; nothing
+ * the API returns contains one, and failures answer with a code, never the request or its values.
+ */
+export async function handleChannelRoutes(req, method, pathname, service, res, json) {
+    const idMatch = pathname.match(/^\/api\/connections\/([^/]+)(?:\/(check|validate-target))?$/);
+    const isCollection = pathname === "/api/connections";
+    const isTest = pathname === "/api/connections/test";
+    const isMeta = pathname === "/api/connections/meta";
+    if (!isCollection && !isTest && !isMeta && !idMatch)
+        return false;
+    try {
+        if (isMeta && method === "GET") {
+            json(res, 200, service.meta());
+            return true;
+        }
+        if (isCollection && method === "GET") {
+            json(res, 200, service.list());
+            return true;
+        }
+        if (isCollection && method === "POST") {
+            json(res, 201, await service.create(await readBody(req)));
+            return true;
+        }
+        if (isTest && method === "POST") {
+            json(res, 200, await service.test(await readBody(req)));
+            return true;
+        }
+        if (idMatch) {
+            let id;
+            try {
+                id = decodeURIComponent(idMatch[1]);
+            }
+            catch {
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            }
+            if (idMatch[2] === "check" && method === "POST") {
+                const health = await service.checkNow(id);
+                if (health)
+                    json(res, 200, health);
+                else
+                    json(res, 404, { code: "CHANNEL_NOT_FOUND" });
+                return true;
+            }
+            if (idMatch[2] === "validate-target" && method === "POST") {
+                json(res, 200, service.validateTarget(id, await readBody(req)));
+                return true;
+            }
+            if (!idMatch[2] && method === "PATCH") {
+                json(res, 200, await service.update(id, await readBody(req)));
+                return true;
+            }
+            if (!idMatch[2] && method === "DELETE") {
+                await service.remove(id);
+                json(res, 200, { removed: true });
+                return true;
+            }
+        }
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_STORAGE_FAILED";
+        json(res, channelErrorStatus(code), { code });
+        return true;
+    }
+    return false;
+}

package/dist/server/http.js

@@ -51,6 +51,7 @@ import { isTaskFile } from "../runtime/taskInput.js";
 import { findTokenShapedField, tokenRejectedPayload, } from "../runtime/startPayload.js";
 import { parseAskOperatorAnswer } from "../tools/askOperator.js";
 import { handleEmailRoutes } from "./emailRoutes.js";
+import { handleChannelRoutes } from "./channelRoutes.js";
 import { bootstrapStageflowHost, } from "./bootstrap.js";
 import { assertAllowedHttpAccess, isTrustedLocalHttpRequest, resolveAllowedHosts, } from "./allowedHosts.js";
 import { enforceBearerAuth, loadControlTokens, requiredScopeFor, } from "./controlToken.js";
@@ -214,6 +215,16 @@ export function createOperatorRoutes(deps) {
             try {
                 if (await liveView.handle(req, res))
                     return true;
+                if (pathname === "/api/connections" || pathname.startsWith("/api/connections/")) {
+                    if (!assertAllowedHttpAccess({ entries: [] }, req, res, { requireOrigin: method !== "GET" }))
+                        return true;
+                    if (!boot.channels) {
+                        json(res, 503, { code: "CHANNEL_CONNECTION_FAILED" });
+                        return true;
+                    }
+                    if (await handleChannelRoutes(req, method, pathname, boot.channels, res, json))
+                        return true;
+                }
                 if (pathname.startsWith("/api/email/")) {
                     if (!assertAllowedHttpAccess({ entries: [] }, req, res, { requireOrigin: ["POST", "PATCH", "DELETE"].includes(method) }))
                         return true;

package/dist/tools/readEmail.d.ts

@@ -6,12 +6,12 @@ export declare function createSearchEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -31,12 +31,12 @@ export declare function createGetEmailTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";
@@ -56,12 +56,12 @@ export declare function createDownloadEmailAttachmentTool(email: StageEmail): {
     description: string;
     parameters: Type.TObject<Type.TProperties>;
     execute(_toolCallId: string, input: unknown): Promise<{
-        isError?: undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: unknown;
+        isError?: undefined;
     } | {
         content: {
             type: "text";

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/types/pipeline.d.ts

@@ -1,4 +1,4 @@
-import type { LoadedStageConfig, StageBrowserConfig, StageGateKind, StageIoYaml } from "./stage.js";
+import type { LoadedStageConfig, StageChannel, 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";
@@ -13,6 +13,8 @@ export type PipelineConfig = {
     schemas?: Record<string, unknown>;
     /** Declared toolchain binaries this pipeline needs (Slot 9). */
     requires?: ToolRequirement[];
+    /** Default channels inherited by every stage that does not override them. */
+    channels?: StageChannel[];
 };
 /** An inline pipeline definition authored directly in a `start_run` call, with no backing file. */
 export type InlinePipelineDefinition = {
@@ -22,6 +24,7 @@ export type InlinePipelineDefinition = {
     model?: unknown;
     schemas?: unknown;
     requires?: unknown;
+    channels?: unknown;
 };
 export type PipelineForkConfig = {
     select: "one" | "subset";

package/dist/types/stage.d.ts

@@ -36,6 +36,17 @@ export type StageBrowserConfig = {
         logged_out_url?: string | string[];
     };
 };
+export type StageChannelOperation = "send";
+/** A pinned communication target for a stage. Targets are validated per provider. */
+export type StageChannel = {
+    alias?: string;
+    connection: string;
+    operations: StageChannelOperation[];
+    to: string | string[];
+    cc?: string[];
+    /** Provider-specific message template, such as a pinned WhatsApp template. Validated by the provider. */
+    template?: Record<string, unknown>;
+};
 export type StageConfig = {
     id: string;
     system_prompt: string;
@@ -56,6 +67,8 @@ export type StageConfig = {
         operations: ("send" | "reply" | "getMessage" | "search" | "downloadAttachment")[];
     }[];
     mcp?: string[];
+    /** Communication channels this stage may send on. Inherits pipeline `channels` defaults. */
+    channels?: StageChannel[];
     /** Declared Host secret names this stage may receive (Slot 6). */
     secrets?: StageSecretDecl[];
     /** Declared toolchain binaries this stage needs (Slot 9). */