stageflow 0.31.0 → 0.32.0

package/dist/runstore/sqlite/migrations/011-email-dispatch-key.d.ts

@@ -0,0 +1,7 @@
+import type Database from "better-sqlite3";
+export declare const MIGRATION_011: {
+    version: number;
+    name: string;
+    minStageflowVersion: string;
+    up(db: Database.Database): void;
+};

package/dist/runstore/sqlite/migrations/011-email-dispatch-key.js

@@ -0,0 +1,12 @@
+import { PACKAGE_VERSION } from "../../../package-meta.js";
+export const MIGRATION_011 = {
+    version: 11,
+    name: "011_email_dispatch_key",
+    minStageflowVersion: PACKAGE_VERSION,
+    up(db) {
+        const columns = db.prepare("PRAGMA table_info(runs)").all();
+        if (!columns.some(column => column.name === "dispatch_key"))
+            db.exec("ALTER TABLE runs ADD COLUMN dispatch_key TEXT");
+        db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_dispatch_key ON runs(dispatch_key)");
+    },
+};

package/dist/runstore/sqlite/migrations/index.js

@@ -9,6 +9,7 @@ import { MIGRATION_007 } from "./007-projects-registry.js";
 import { MIGRATION_008 } from "./008-triggers-table.js";
 import { MIGRATION_009 } from "./009-trigger-next-run.js";
 import { MIGRATION_010 } from "./010-trigger-adapter-state.js";
+import { MIGRATION_011 } from "./011-email-dispatch-key.js";
 const DEFAULT_MIGRATIONS = [
     MIGRATION_001,
     MIGRATION_002,
@@ -20,6 +21,7 @@ const DEFAULT_MIGRATIONS = [
     MIGRATION_008,
     MIGRATION_009,
     MIGRATION_010,
+    MIGRATION_011,
 ];
 export const CURRENT_SCHEMA_VERSION = DEFAULT_MIGRATIONS[DEFAULT_MIGRATIONS.length - 1].version;
 function throwStoreSchemaTooNew(db, version, maxKnown) {

package/dist/runtime/pipelineRunner.d.ts

@@ -41,6 +41,7 @@ export type PipelineRunResult = {
     findings?: ValidationFinding[];
 };
 export type StartedPipeline = {
+    created?: boolean;
     runId: string;
     runDir: string;
     done: Promise<PipelineRunResult>;
@@ -51,6 +52,7 @@ export type PreparedPipeline = {
     run: {
         runId: string;
         workspaceDir: string;
+        created?: boolean;
     };
     agent: AgentPort;
     store: RunStore;
@@ -97,6 +99,7 @@ export declare function runPipeline(options: {
 }): Promise<PipelineRunResult>;
 /** Create the run immediately, then execute stages in the returned promise. */
 export declare function startPipeline(options: {
+    dispatchKey?: string;
     submission?: RunSubmission;
     agent: AgentPort;
     store: RunStore;

package/dist/runtime/pipelineRunner.js

@@ -197,6 +197,7 @@ async function preparePipeline(options) {
             namedSecrets,
         });
         run = await options.store.createRun({
+            dispatchKey: options.dispatchKey,
             submission: options.submission,
             runId,
             pipelineId: loaded.pipeline.id,
@@ -299,6 +300,7 @@ export async function startPipeline(options) {
     const cwd = options.cwd ?? process.cwd();
     const projectRoot = options.projectRoot ?? cwd;
     const prepared = await preparePipeline({
+        dispatchKey: options.dispatchKey,
         submission: options.submission,
         agent: options.agent,
         store: options.store,
@@ -327,6 +329,15 @@ export async function startPipeline(options) {
         callerId: options.callerId,
         ...(options.skills !== undefined ? { skills: options.skills } : {}),
     });
+    if (prepared.run.created === false) {
+        const meta = await prepared.store.readRunMeta(prepared.run.runId);
+        return {
+            created: false,
+            runId: prepared.run.runId,
+            runDir: prepared.run.workspaceDir,
+            done: Promise.resolve({ ok: meta.status === "succeeded", outcome: meta.status === "succeeded" ? "succeeded" : "failed", runId: prepared.run.runId, runDir: prepared.run.workspaceDir, reason: "Recovered existing dispatch; execution was not restarted" }),
+        };
+    }
     const done = executeStages(prepared, {
         maxActiveStagesPerRun: options.maxActiveStagesPerRun,
         executionMode: prepared.executionMode,

package/dist/runtime/pipelineScheduler.js

@@ -968,6 +968,9 @@ export async function runPipelineDag(options) {
                     runId: run.runId,
                     stageId,
                     rootDir: factoryCwd,
+                    stage,
+                    factoryCwd,
+                    workspaceDir: run.workspaceDir,
                     attempt,
                     env: stageBinding.env,
                     bindingKind: stageBinding.kind,

package/dist/runtime/runManager.d.ts

@@ -285,6 +285,7 @@ export declare class RunManager {
         pipeline: string | InlinePipelineDefinition;
         task?: string | TaskFile;
         checkoutOverride?: string;
+        dispatchKey?: string;
         skipGates?: boolean;
         gitSha?: string;
         ciPrUrl?: string;

package/dist/runtime/runManager.js

@@ -1153,6 +1153,15 @@ export class RunManager {
                 ? (findProjectRoot(path.dirname(path.resolve(hostCwd, input.pipeline))) ?? this.projectRoot)
                 : this.projectRoot);
         const cwd = wireRoot ?? hostCwd;
+        if (input.dispatchKey) {
+            if (!this.options.store.findRunByDispatchKey)
+                throw new Error("Run store does not support durable dispatch");
+            const existing = await this.options.store.findRunByDispatchKey(input.dispatchKey);
+            if (existing) {
+                const meta = await this.options.store.readRunMeta(existing.runId);
+                return { ok: true, runId: existing.runId, done: Promise.resolve({ ok: meta.status === "succeeded", outcome: meta.status === "succeeded" ? "succeeded" : "failed", runId: existing.runId, runDir: existing.workspaceDir, reason: "Recovered existing dispatch; execution was not restarted" }) };
+            }
+        }
         let resolved;
         try {
             resolved = resolveStartTaskInput(input, cwd);
@@ -1187,7 +1196,7 @@ export class RunManager {
             gitSha: input.gitSha,
             ciPrUrl: input.ciPrUrl,
             ciJobUrl: input.ciJobUrl,
-        }, derivedProjectRoot, resolved.kind === "path" ? resolved.taskPath : undefined, submission, undefined, input.callerId, input.skills);
+        }, derivedProjectRoot, resolved.kind === "path" ? resolved.taskPath : undefined, submission, undefined, input.callerId, input.skills, input.dispatchKey);
     }
     async rerun(runId, options) {
         if (!this.acceptingWork) {
@@ -1972,6 +1981,9 @@ export class RunManager {
                 runId,
                 stageId,
                 rootDir: runProjectRoot,
+                factoryCwd: runProjectRoot,
+                stage: resumedStage,
+                workspaceDir,
                 ...(browserEnv !== undefined ? { browserEnv } : {}),
                 mode: "resume",
                 resumeAnswer: opaqueAnswer,
@@ -2135,7 +2147,7 @@ export class RunManager {
             this.attachedWaiting.delete(`${runId}\0${stageId}`);
         }
     }
-    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath, submission, pinned, callerId, skills) {
+    async reserveAndStartPipeline(taskYaml, pipeline, taskLabel, cwd, checkoutOverride, skipGates, ciIdentity, projectRoot, taskPath, submission, pinned, callerId, skills, dispatchKey) {
         const persistence = pipelinePersistenceForStart(pipeline);
         if (!persistence.ok) {
             return {
@@ -2308,6 +2320,7 @@ export class RunManager {
                 namedSecrets,
             });
             const created = await this.options.store.createRun({
+                dispatchKey,
                 submission,
                 runId,
                 pipelineId,
@@ -2335,6 +2348,10 @@ export class RunManager {
                 runManifest,
                 skipGates,
             });
+            if (created.created === false) {
+                const existing = await this.options.store.readRunMeta(created.runId);
+                return { ok: true, runId: created.runId, done: Promise.resolve({ ok: existing.status === "succeeded", outcome: existing.status === "succeeded" ? "succeeded" : "failed", runId: created.runId, runDir: created.workspaceDir, reason: "Recovered existing dispatch; execution was not restarted" }) };
+            }
             if (hasSkills) {
                 await materializeRunSkills(created.workspaceDir, validatedSkills);
             }
@@ -2387,6 +2404,7 @@ export class RunManager {
             rollback = linkRollback;
             const schedulingHalt = this.ensureSchedulingHalt(materialized.runId);
             const started = await startPipeline({
+                dispatchKey,
                 submission,
                 ...(this.options.browser !== undefined
                     ? { browser: this.options.browser }
@@ -2418,7 +2436,10 @@ export class RunManager {
                 callerId,
                 ...(hasSkills ? { skills: validatedSkills } : {}),
             });
-            this.track(admitted.provisionalId, started.runId, started.done);
+            if (started.created === false)
+                this.clearReservation(admitted.provisionalId);
+            else
+                this.track(admitted.provisionalId, started.runId, started.done);
             return { ok: true, runId: started.runId, done: started.done };
         }
         catch (err) {

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,3 +1,5 @@
+import { emailHostFor, stageEmail, workerStageEmail, validateStageEmailAccounts } from "../email/host.js";
+import { EmailError } from "../email/port.js";
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
 import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
 import { humanLoginPromptBlock, isHumanLoginStage } from "../browser/humanLogin.js";
@@ -429,6 +431,16 @@ export async function openStageAttempt(input) {
     const meta = await input.store.readRunMeta(input.runId);
     const bindingKind = input.bindingKind ?? bindingKindFromMeta(meta);
     const trustWorkspaceConfig = resolveTrustWorkspaceConfig(input.trustWorkspaceConfig);
+    if (process.env.SF_STAGE_WORKER !== "1" && input.stage.email?.length) {
+        try {
+            validateStageEmailAccounts(emailHostFor(input.factoryCwd ?? process.cwd()).accounts, input.stage);
+        }
+        catch (error) {
+            if (error instanceof EmailError)
+                return { ok: false, reason: error.code };
+            throw error;
+        }
+    }
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -442,6 +454,8 @@ export async function openStageAttempt(input) {
             ? { priorEnvelopesByStage: priorResult.priorEnvelopesByStage }
             : {}),
         resumeToken,
+        email: input.stage.email?.length ? (process.env.SF_STAGE_WORKER === "1" ? workerStageEmail()
+            : stageEmail(emailHostFor(input.factoryCwd ?? process.cwd()).mailbox, input.stage, input.runId, { workspaceDir: input.workspaceDir, attempt })) : undefined,
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
             input.onActivity?.(input.stage.browser !== undefined

package/dist/runtime/stageProcessLauncher.d.ts

@@ -2,16 +2,20 @@ import * as childProcess from "node:child_process";
 import { type Logger } from "../logging/logger.js";
 import { type ResolvedStageGrants } from "./stageEnvironment.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+import type { StageConfig } from "../types/stage.js";
 import { type DerivedBindingKind } from "./stageRoots.js";
 export type StageLaunchInput = {
     runId: string;
     stageId: string;
     rootDir: string;
+    workspaceDir?: string;
     mode?: "run" | "resume" | "feedback_resume" | "new_session";
     resumeAnswer?: unknown;
     attempt?: number;
     sessionFilePath?: string;
     operatorCatalog?: OperatorCatalog;
+    factoryCwd?: string;
+    stage?: StageConfig;
     skipGates?: boolean;
     env?: Record<string, string>;
     bindingKind?: DerivedBindingKind;

package/dist/runtime/stageProcessLauncher.js

@@ -12,6 +12,8 @@ import { getContainerLimits } from "./containerLimits.js";
 import { buildStageEnvironment, isAmbientBlockedEnv, isForeverDeniedSecret, } from "./stageEnvironment.js";
 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 { EmailError } from "../email/port.js";
 import { overlayStageBindingEnv, } from "./stageRoots.js";
 function defaultStageCliEntry() {
     const source = import.meta.url.split("?")[0]?.endsWith(".ts") === true;
@@ -178,6 +180,16 @@ export class StageProcessLauncher {
         }
     }
     async launch(input) {
+        try {
+            if (input.stage?.email?.length)
+                validateStageEmailAccounts(emailHostFor(input.factoryCwd ?? input.operatorCatalog?.cwd ?? input.rootDir).accounts, input.stage);
+        }
+        catch (error) {
+            if (error instanceof EmailError)
+                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) {
             return { type: "failed", reason: "cancelled" };
@@ -279,6 +291,7 @@ export class StageProcessLauncher {
         }
     }
     spawnAndWait(input) {
+        const factoryCwd = input.factoryCwd ?? input.operatorCatalog?.cwd ?? input.rootDir;
         const mode = input.mode ?? (input.resumeAnswer !== undefined ? "resume" : "run");
         const args = [
             "internal",
@@ -350,7 +363,7 @@ export class StageProcessLauncher {
         }
         const child = this.forkFn(this.cliEntry, args, {
             cwd: input.rootDir,
-            env: { ...childEnv, [SF_STAGE_WORKER]: "1" },
+            env: emailWorkerEnvironment({ ...childEnv, [SF_STAGE_WORKER]: "1" }, emailHostFor(factoryCwd).accounts),
             stdio: ["pipe", "pipe", "pipe", "ipc"],
             detached: true,
             // Explicit: do not inherit Host execArgv; set heap from cgroup budget.
@@ -388,6 +401,37 @@ export class StageProcessLauncher {
                 resolve(result);
             };
             child.on("message", (message) => {
+                const request = message;
+                if (!settled && ["email.send", "email.reply", "email.search", "email.getMessage", "email.downloadAttachment"].includes(request?.type ?? "")) {
+                    void (async () => {
+                        if (typeof request.requestId !== "string" || request.requestId.length > 100)
+                            return;
+                        let response;
+                        try {
+                            const stage = input.stage;
+                            if (!stage || settled)
+                                throw new EmailError("EMAIL_UNAUTHORIZED");
+                            const email = stageEmail(emailHostFor(factoryCwd).mailbox, stage, input.runId, input.workspaceDir ? { workspaceDir: input.workspaceDir, attempt: input.attempt ?? 1 } : undefined);
+                            if (request.type === "email.send")
+                                response = { receipt: await email.send(request.input) };
+                            else if (request.type === "email.reply")
+                                response = { receipt: await email.reply(request.input) };
+                            else if (request.type === "email.search")
+                                response = { result: await email.search(request.input) };
+                            else if (request.type === "email.getMessage")
+                                response = { result: await email.getMessage(request.input) };
+                            else
+                                response = { result: await email.downloadAttachment(request.input) };
+                        }
+                        catch (error) {
+                            const fault = error instanceof EmailError ? error : new EmailError("EMAIL_UNAUTHORIZED");
+                            response = { error: { code: fault.code, retryable: fault.retryable, ...(fault.unsupportedFields ? { unsupportedFields: fault.unsupportedFields } : {}) } };
+                        }
+                        if (child.connected && !settled)
+                            child.send({ type: "email.response", requestId: request.requestId, ...response });
+                    })();
+                    return;
+                }
                 if (!isStageWorkerResult(message))
                     return;
                 finish(resultFromWorkerMessage(message));

package/dist/server/bootstrap.d.ts

@@ -5,6 +5,8 @@ import { type RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
 import type { StoreFilesystemClassification } from "../runstore/storeFilesystem.js";
 import { RunManager } from "../runtime/runManager.js";
+import { emailHostFor } from "../email/host.js";
+import { EmailTriggers } from "../email/triggers.js";
 import { type RunChangeBus } from "../runtime/runChangeBus.js";
 import { type McpHttpHandler } from "../mcp/server.js";
 import { type HostConfig } from "../config/hostConfig.js";
@@ -25,6 +27,7 @@ export type StageflowHostOptions = {
     hostConfig?: HostConfig;
     /** Skip HostConfig load (tests that inject store/manager pieces only). */
     skipHostConfig?: boolean;
+    emailTriggerQueue?: ConstructorParameters<typeof EmailTriggers>[0]["queue"];
 };
 export type StageflowHostBootstrap = {
     a2a?: A2aHost;
@@ -51,6 +54,10 @@ export type StageflowHostBootstrap = {
     stopGithubPollSource: () => void;
     /** Stops the email-trigger IMAP/IDLE listeners started at boot. */
     stopEmailSource: () => void;
+    email?: ReturnType<typeof emailHostFor> & {
+        triggers: EmailTriggers;
+        stop: () => Promise<void>;
+    };
     /** Filesystem classification for `$STAGEFLOW_HOME` (Slot 8). */
     storeFilesystem?: StoreFilesystemClassification;
     /**

package/dist/server/bootstrap.js

@@ -15,6 +15,8 @@ import { PI_CODING_AGENT_DIR_ENV } from "../runtime/stageRoots.js";
 import { ScheduleSource, triggerTickIntervalMsFromEnv, } from "../runtime/scheduleSource.js";
 import { GithubPollSource, githubPollIntervalMsFromEnv, } from "../runtime/githubPollSource.js";
 import { EmailSource } from "../runtime/emailSource.js";
+import { emailHostFor, releaseEmailHost } from "../email/host.js";
+import { EmailTriggers } from "../email/triggers.js";
 import { fireTrigger } from "../runtime/triggerRunner.js";
 import { createRunChangeBus, getRunChangeBusFromWrappedStore, isRunStoreWrapped, wrapRunStoreWithChangeBus, } from "../runtime/runChangeBus.js";
 import { createMcpHttpHandler, resolveMcpStateless, } from "../mcp/server.js";
@@ -111,6 +113,8 @@ export async function bootstrapStageflowHost(options) {
     process.env[PI_CODING_AGENT_DIR_ENV] = path.join(ctx.globalHome, "agent");
     const agentDir = options.agentDir ?? getAgentDir();
     const rootDir = options.rootDir ?? ctx.projectRoot;
+    // Validate project account configuration before starting host resources.
+    const emailHost = emailHostFor(rootDir);
     const isGitProject = options.rootDir !== undefined
         ? findProjectRoot(rootDir) !== null
         : ctx.isGitProject;
@@ -303,8 +307,20 @@ export async function bootstrapStageflowHost(options) {
         logError: (message) => bootLog.error("trigger.email_source_failed", message),
     });
     await emailSource.start(onTriggerFire);
+    const emailTriggers = new EmailTriggers({ cwd: rootDir, accounts: emailHost.accounts, mailbox: emailHost.mailbox, manager, store, queue: options.emailTriggerQueue });
+    let stoppingEmail;
+    const stopAccountEmail = () => stoppingEmail ??= Promise.all([emailTriggers.stop(), releaseEmailHost(rootDir)]).then(() => undefined);
+    void emailTriggers.recover().catch(() => undefined);
+    try {
+        await emailHost.mailbox.start(event => emailTriggers.accept(event));
+    }
+    catch (error) {
+        await Promise.all([stopAccountEmail(), emailSource.stop(), scheduleSource.stop(), githubPollSource.stop()]);
+        throw error;
+    }
     const stopEmailSource = () => {
         void emailSource.stop();
+        void stopAccountEmail();
     };
     const mcpStateless = resolveMcpStateless({
         mcpStateless: options.mcpStateless,
@@ -344,6 +360,7 @@ export async function bootstrapStageflowHost(options) {
         stopScheduleSource,
         stopGithubPollSource,
         stopEmailSource,
+        email: { ...emailHost, triggers: emailTriggers, stop: stopAccountEmail },
         storeFilesystem,
     };
 }

package/dist/server/emailRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { EmailAccounts } from "../email/accounts.js";
+import { type EmailMailbox } from "../email/port.js";
+import type { EmailTriggers } from "../email/triggers.js";
+export declare function handleEmailRoutes(req: IncomingMessage, res: ServerResponse, pathname: string, accounts: EmailAccounts, mailbox: EmailMailbox, triggers?: EmailTriggers): Promise<void>;

package/dist/server/emailRoutes.js

@@ -0,0 +1,136 @@
+import { EmailError } from "../email/port.js";
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(body));
+}
+async function body(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += Buffer.byteLength(chunk);
+        if (size > 32768)
+            throw new EmailError("EMAIL_RESOURCE_LIMIT");
+        chunks.push(Buffer.from(chunk));
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    }
+    catch {
+        throw new EmailError("EMAIL_INVALID_INPUT");
+    }
+}
+export async function handleEmailRoutes(req, res, pathname, accounts, mailbox, triggers) {
+    try {
+        const method = req.method ?? "GET";
+        if (triggers) {
+            if (["/api/email/replay/preview", "/api/email/replay/execute"].includes(pathname) && method === "POST") {
+                json(res, 200, await triggers.replay(await body(req), pathname.endsWith("execute")));
+                return;
+            }
+            const triggerMatch = pathname.match(/^\/api\/email\/triggers\/([^/]+)$/);
+            if (pathname === "/api/email/triggers" && method === "GET") {
+                json(res, 200, { triggers: triggers.list() });
+                return;
+            }
+            if (pathname === "/api/email/triggers" && method === "POST") {
+                json(res, 201, await triggers.create(await body(req)));
+                return;
+            }
+            if (pathname === "/api/email/dispatches" && method === "GET") {
+                json(res, 200, { dispatches: triggers.history() });
+                return;
+            }
+            if (pathname === "/api/email/dispatches/health" && method === "GET") {
+                json(res, 200, triggers.health());
+                return;
+            }
+            const dispatchMatch = pathname.match(/^\/api\/email\/dispatches\/([^/]+)\/(resume|cancel)$/);
+            if (dispatchMatch && method === "POST") {
+                const input = await body(req);
+                if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).length)
+                    throw new EmailError("EMAIL_INVALID_INPUT");
+                const key = decodeURIComponent(dispatchMatch[1]);
+                if (dispatchMatch[2] === "resume")
+                    json(res, 200, triggers.resume(key));
+                else {
+                    triggers.cancel(key);
+                    json(res, 200, { cancelled: true });
+                }
+                return;
+            }
+            if (triggerMatch) {
+                const id = decodeURIComponent(triggerMatch[1]);
+                if (method === "GET") {
+                    json(res, 200, triggers.get(id));
+                    return;
+                }
+                if (method === "PATCH") {
+                    json(res, 200, await triggers.update(id, await body(req)));
+                    return;
+                }
+                if (method === "DELETE") {
+                    triggers.remove(id);
+                    json(res, 200, { removed: true });
+                    return;
+                }
+            }
+        }
+        if (["/api/email/events", "/api/email/watchers"].includes(pathname) && method === "GET") {
+            const adapter = mailbox;
+            json(res, 200, pathname.endsWith("events") ? { events: adapter.events?.list() ?? [] } : { watchers: adapter.events?.health() ?? [] });
+            return;
+        }
+        if (pathname === "/api/email/submissions" && method === "GET") {
+            const adapter = mailbox;
+            json(res, 200, { submissions: adapter.submissions?.list() ?? [] });
+            return;
+        }
+        const match = pathname.match(/^\/api\/email\/accounts\/([^/]+)(?:\/(test|health))?$/);
+        if (pathname === "/api/email/accounts" && method === "GET") {
+            json(res, 200, { accounts: accounts.list() });
+            return;
+        }
+        if (pathname === "/api/email/accounts" && method === "POST") {
+            json(res, 201, accounts.create(await body(req)));
+            return;
+        }
+        if (match) {
+            const accountId = decodeURIComponent(match[1]);
+            if (!match[2] && method === "GET") {
+                json(res, 200, accounts.get(accountId, false));
+                return;
+            }
+            if (!match[2] && method === "PATCH") {
+                json(res, 200, accounts.update(accountId, await body(req)));
+                return;
+            }
+            if (!match[2] && method === "DELETE") {
+                accounts.remove(accountId);
+                json(res, 200, { removed: true });
+                return;
+            }
+            if (match[2] === "health" && method === "GET") {
+                json(res, 200, { health: accounts.health(accountId) ?? null });
+                return;
+            }
+            if (match[2] === "test" && method === "POST") {
+                const input = await body(req);
+                if (!input || typeof input !== "object" || Array.isArray(input) ||
+                    Object.keys(input).some(key => key !== "protocol") ||
+                    (input.protocol !== undefined && !["imap", "smtp", "both"].includes(String(input.protocol)))) {
+                    throw new EmailError("EMAIL_INVALID_INPUT");
+                }
+                json(res, 200, await mailbox.testAccount(accountId, input.protocol));
+                return;
+            }
+        }
+        json(res, 404, { error: "Not found" });
+    }
+    catch (error) {
+        const fault = error instanceof EmailError ? error : new EmailError("EMAIL_CONNECTION_FAILED", true);
+        const status = fault.code === "EMAIL_ACCOUNT_NOT_FOUND" ? 404 :
+            fault.code === "EMAIL_ACCOUNT_DISABLED" ? 409 :
+                fault.code === "EMAIL_RESOURCE_LIMIT" ? 413 : 400;
+        json(res, status, { error: fault.code, code: fault.code, retryable: fault.retryable, ...(fault.unsupportedFields ? { unsupportedFields: fault.unsupportedFields } : {}) });
+    }
+}

package/dist/server/http.d.ts

@@ -6,6 +6,7 @@ import type { RunStoreKind } from "../runstore/createStore.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunManager } from "../runtime/runManager.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
+import { EmailTriggers } from "../email/triggers.js";
 import { type AllowedHosts } from "./allowedHosts.js";
 import { type ControlTokens } from "./controlToken.js";
 import { DEFAULT_PORT, type HttpHostEnvelope, type HttpHostRouteContext } from "./createHttpHost.js";
@@ -21,6 +22,7 @@ export type UiServerOptions = {
     host?: string;
     uiDistDir?: string;
     maxConcurrent?: number;
+    emailTriggerQueue?: ConstructorParameters<typeof EmailTriggers>[0]["queue"];
     providerAuthContext?: ProviderAuthContext;
     mcpStateless?: boolean;
     runChangeBus?: RunChangeBus;

package/dist/server/http.js

@@ -38,6 +38,7 @@ import { INVALID_SLOT_COUNT_MESSAGE, INVALID_WORKSHOP_MODEL_MESSAGE, parseSlotCo
 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 { bootstrapStageflowHost, } from "./bootstrap.js";
 import { assertAllowedHttpAccess, isTrustedLocalHttpRequest, resolveAllowedHosts, } from "./allowedHosts.js";
 import { enforceBearerAuth, loadControlTokens, requiredScopeFor, } from "./controlToken.js";
@@ -192,6 +193,17 @@ export function createOperatorRoutes(deps) {
         return handleOperatorRequest();
         async function handleOperatorRequest() {
             try {
+                if (pathname.startsWith("/api/email/")) {
+                    if (!assertAllowedHttpAccess({ entries: [] }, req, res, { requireOrigin: ["POST", "PATCH", "DELETE"].includes(method) }))
+                        return true;
+                    const email = boot.email;
+                    if (!email) {
+                        json(res, 503, { code: "EMAIL_CONNECTION_FAILED" });
+                        return true;
+                    }
+                    await handleEmailRoutes(req, res, pathname, email.accounts, email.mailbox, email.triggers);
+                    return true;
+                }
                 if (method === "GET" && pathname === "/api/runs") {
                     const filter = {};
                     const status = url.searchParams.get("status");
@@ -2470,6 +2482,10 @@ export async function startUiServer(options) {
         controlTokens,
         routes,
     });
+    const closeServer = envelope.server.close.bind(envelope.server);
+    envelope.server.close = ((callback) => closeServer(error => {
+        void (boot.email?.stop() ?? Promise.resolve()).then(() => callback?.(error), () => callback?.(error ?? new Error("Email host shutdown failed")));
+    }));
     shutdown = installShutdownController({
         server: envelope.server,
         host: makeDrainableHostFromOptional(envelope.manager, envelope.store),