stageflow 0.30.0 → 0.32.0

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -189,9 +189,13 @@ export class SqliteRunStore {
     }
     async createRun(input) {
         await this.ready();
+        const existing = input.dispatchKey ? await this.findRunByDispatchKey(input.dispatchKey) : undefined;
+        if (existing)
+            return existing;
         const runId = input.runId ?? newRunId();
         const workspaceDir = this.getWorkspaceDir(runId);
-        await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
+        if (!input.dispatchKey)
+            await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
         const now = new Date().toISOString();
         const pipelinePath = input.pipelinePath
             ? normalizeCatalogPath(input.pipelinePath)
@@ -214,13 +218,15 @@ export class SqliteRunStore {
                 if (existing)
                     throw new RunSubmissionExistsError(existing);
             }
-            this.db
+            const inserted = this.db
                 .prepare(`INSERT INTO runs
-          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, repository, ref, resolved_sha, run_branch, git_author_name, git_author_email, pipeline_source, pipeline_body, caller_id, run_manifest, skip_gates)
+          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root, repository, ref, resolved_sha, run_branch, git_author_name, git_author_email, pipeline_source, pipeline_body, caller_id, run_manifest, skip_gates, dispatch_key)
          VALUES
-          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root, @repository, @ref, @resolved_sha, @run_branch, @git_author_name, @git_author_email, @pipeline_source, @pipeline_body, @caller_id, @run_manifest, @skip_gates)`)
+          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root, @repository, @ref, @resolved_sha, @run_branch, @git_author_name, @git_author_email, @pipeline_source, @pipeline_body, @caller_id, @run_manifest, @skip_gates, @dispatch_key)
+          ON CONFLICT(dispatch_key) DO NOTHING`)
                 .run({
                 run_id: runId,
+                dispatch_key: input.dispatchKey ?? null,
                 pipeline_id: input.pipelineId,
                 task_id: input.taskId ?? null,
                 task_yaml: input.taskYaml,
@@ -251,12 +257,25 @@ export class SqliteRunStore {
                     : null,
                 skip_gates: input.skipGates === undefined ? null : input.skipGates ? 1 : 0,
             });
+            if (!inserted.changes)
+                return;
             if (input.submission) {
                 this.db.prepare("INSERT INTO run_submissions (submission_key, request_hash, run_id) VALUES (?, ?, ?)")
                     .run(input.submission.key, input.submission.requestHash, runId);
             }
         })();
-        return { runId, workspaceDir };
+        if (input.dispatchKey) {
+            const selected = await this.findRunByDispatchKey(input.dispatchKey);
+            if (selected && selected.runId !== runId)
+                return selected;
+            await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
+        }
+        return { runId, workspaceDir, ...(input.dispatchKey ? { created: true } : {}) };
+    }
+    async findRunByDispatchKey(dispatchKey) {
+        await this.ready();
+        const row = this.db.prepare("SELECT run_id FROM runs WHERE dispatch_key = ?").get(dispatchKey);
+        return row ? { runId: row.run_id, workspaceDir: this.getWorkspaceDir(row.run_id), created: false } : undefined;
     }
     readSubmission(key) {
         const row = this.db.prepare("SELECT submission_key AS key, request_hash AS requestHash, run_id AS runId FROM run_submissions WHERE submission_key = ?")

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

@@ -7,14 +7,17 @@ export type CredentialBinding = {
     provisional: boolean;
 };
 export type ResolveCredentialBindingOptions = {
-    piHomeAuthPath?: string;
+    agentAuthPath?: string;
 };
 export declare function sfOwnedAgentDir(): string;
 export declare function sfOwnedAuthPath(): string;
-export declare const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
-/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
+export declare const STAGEFLOW_AGENT_AUTH_PATH_ENV = "STAGEFLOW_AGENT_AUTH_PATH";
+/** @deprecated Use STAGEFLOW_AGENT_AUTH_PATH_ENV. */
+export declare const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_AGENT_AUTH_PATH";
+export declare function stageflowAgentAuthPath(override?: string): string;
+/** @deprecated Use stageflowAgentAuthPath */
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
 export declare function ensureSfOwnedAuthStore(): string;
-export declare function resolveCredentialBinding(ctx: ProjectContext | string, options?: ResolveCredentialBindingOptions): CredentialBinding;
+export declare function resolveCredentialBinding(ctx: ProjectContext | string, _options?: ResolveCredentialBindingOptions): CredentialBinding;
 export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

package/dist/runtime/credentialBinding.js

@@ -1,5 +1,4 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { ensureGlobalHome } from "../project/globalHome.js";
 import { resolveProjectContext, } from "../project/resolveProjectContext.js";
@@ -11,12 +10,23 @@ export function sfOwnedAgentDir() {
 export function sfOwnedAuthPath() {
     return path.join(sfOwnedAgentDir(), "auth.json");
 }
-export const PI_HOME_AUTH_PATH_ENV = "STAGEFLOW_PI_HOME_AUTH_PATH";
-/** A stage worker's HOME is an empty attempt dir, so the Host passes its own Pi auth path through the environment. */
+export const STAGEFLOW_AGENT_AUTH_PATH_ENV = "STAGEFLOW_AGENT_AUTH_PATH";
+/** @deprecated Use STAGEFLOW_AGENT_AUTH_PATH_ENV. */
+export const PI_HOME_AUTH_PATH_ENV = STAGEFLOW_AGENT_AUTH_PATH_ENV;
+export function stageflowAgentAuthPath(override) {
+    if (override !== undefined) {
+        return path.resolve(override);
+    }
+    const fromEnv = process.env[STAGEFLOW_AGENT_AUTH_PATH_ENV]?.trim() ||
+        process.env.STAGEFLOW_PI_HOME_AUTH_PATH?.trim();
+    if (fromEnv) {
+        return path.resolve(fromEnv);
+    }
+    return sfOwnedAuthPath();
+}
+/** @deprecated Use stageflowAgentAuthPath */
 export function piHomeAuthPath(override) {
-    return (override ??
-        (process.env[PI_HOME_AUTH_PATH_ENV] || undefined) ??
-        path.join(os.homedir(), ".pi", "agent", "auth.json"));
+    return stageflowAgentAuthPath(override);
 }
 export function isUsableAuthFile(authPath) {
     if (!existsSync(authPath))
@@ -43,35 +53,14 @@ export function ensureSfOwnedAuthStore() {
     }
     return authPath;
 }
-export function resolveCredentialBinding(ctx, options = {}) {
+export function resolveCredentialBinding(ctx, _options = {}) {
     const projectCtx = typeof ctx === "string" ? resolveProjectContext(ctx) : ctx;
-    const piHome = piHomeAuthPath(options.piHomeAuthPath);
     const persisted = readCredentialSourceFromContext(projectCtx);
-    if (persisted !== undefined) {
-        if (persisted === "sf_owned") {
-            return {
-                source: "sf_owned",
-                authPath: ensureSfOwnedAuthStore(),
-                provisional: false,
-            };
-        }
-        return {
-            source: "pi_home",
-            authPath: piHome,
-            provisional: false,
-        };
-    }
-    if (isUsableAuthFile(piHome)) {
-        return {
-            source: "pi_home",
-            authPath: piHome,
-            provisional: true,
-        };
-    }
+    const authPath = ensureSfOwnedAuthStore();
     return {
         source: "sf_owned",
-        authPath: ensureSfOwnedAuthStore(),
-        provisional: true,
+        authPath,
+        provisional: persisted === undefined,
     };
 }
 export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";

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,9 +968,13 @@ export async function runPipelineDag(options) {
                     runId: run.runId,
                     stageId,
                     rootDir: factoryCwd,
+                    stage,
+                    factoryCwd,
+                    workspaceDir: run.workspaceDir,
                     attempt,
                     env: stageBinding.env,
                     bindingKind: stageBinding.kind,
+                    model: stage.model,
                     grants,
                     attemptHome,
                     ...(browserEnv !== undefined ? { browserEnv } : {}),

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,
@@ -1979,6 +1991,7 @@ export class RunManager {
                 sessionFilePath,
                 env: stageBinding.env,
                 bindingKind: stageBinding.kind,
+                ...(resumedStage !== undefined ? { model: resumedStage.model } : {}),
                 ...(this.options.operatorCatalog !== undefined
                     ? { operatorCatalog: this.options.operatorCatalog }
                     : {}),
@@ -2134,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 {
@@ -2307,6 +2320,7 @@ export class RunManager {
                 namedSecrets,
             });
             const created = await this.options.store.createRun({
+                dispatchKey,
                 submission,
                 runId,
                 pipelineId,
@@ -2334,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);
             }
@@ -2386,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 }
@@ -2417,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) {
@@ -2506,17 +2528,26 @@ export class RunManager {
         };
     }
     async checkDiskFloorAdmission() {
+        const raw = process.env.STAGEFLOW_MIN_FREE_DISK_BYTES;
+        if (raw === undefined || raw.trim() === "") {
+            return undefined;
+        }
         try {
             const readFree = this.options.freeSpaceReader ?? readFilesystemSize;
             const size = await readFree(globalStageflowHome());
-            const minFreeBytes = resolveMinFreeDiskFloor(process.env.STAGEFLOW_MIN_FREE_DISK_BYTES, size.totalBytes);
+            const minFreeBytes = resolveMinFreeDiskFloor(raw, size.totalBytes);
+            if (minFreeBytes === 0) {
+                return undefined;
+            }
             if (size.freeBytes < minFreeBytes) {
                 return this.insufficientDiskFailure(size.freeBytes, minFreeBytes);
             }
             return undefined;
         }
         catch (err) {
-            // Default floor is always active via resolveMinFreeDiskFloor — fail closed.
+            if (resolveMinFreeDiskFloor(raw, 0) === 0 && !raw.trim().endsWith("%")) {
+                return undefined;
+            }
             return {
                 ok: false,
                 reason: `Disk free-space check failed: ${err instanceof Error ? err.message : String(err)}`,

package/dist/runtime/settingsFile.d.ts

@@ -2,9 +2,9 @@ import type { ProjectContext } from "../project/resolveProjectContext.js";
 import type { StageflowContext } from "../project/resolveStageflowContext.js";
 export declare const SETTINGS_FILE_NAME = "settings.json";
 export declare const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
-export declare const INVALID_CREDENTIAL_SOURCE_MESSAGE = "credentialSource must be \"pi_home\" or \"sf_owned\"";
+export declare const INVALID_CREDENTIAL_SOURCE_MESSAGE = "credentialSource must be \"sf_owned\"";
 export declare const INVALID_WORKSHOP_MODEL_MESSAGE = "workshopModel must be a non-empty string";
-export type CredentialSource = "pi_home" | "sf_owned";
+export type CredentialSource = "sf_owned";
 export type FactorySettings = {
     maxConcurrent?: number;
     credentialSource?: CredentialSource;

package/dist/runtime/settingsFile.js

@@ -5,7 +5,7 @@ import { globalStageflowHome } from "../project/globalHome.js";
 import { storeRootFor } from "../runstore/paths.js";
 export const SETTINGS_FILE_NAME = "settings.json";
 export const INVALID_SLOT_COUNT_MESSAGE = "maxConcurrent must be an integer >= 1";
-export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "pi_home" or "sf_owned"';
+export const INVALID_CREDENTIAL_SOURCE_MESSAGE = 'credentialSource must be "sf_owned"';
 export const INVALID_WORKSHOP_MODEL_MESSAGE = "workshopModel must be a non-empty string";
 export function globalSettingsFilePath() {
     return path.join(globalStageflowHome(), SETTINGS_FILE_NAME);
@@ -29,9 +29,12 @@ export function parseSlotCount(value) {
     return value;
 }
 export function parseCredentialSource(value) {
-    if (value === "pi_home" || value === "sf_owned") {
+    if (value === "sf_owned") {
         return value;
     }
+    if (value === "pi_home") {
+        return "sf_owned";
+    }
     return undefined;
 }
 export function parseWorkshopModelSetting(value) {

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,22 +2,27 @@ 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;
     grants?: ResolvedStageGrants;
     attemptHome?: string;
     browserEnv?: Record<string, string>;
+    model?: string;
 };
 export type StageLaunchResult = {
     type: "succeeded";

package/dist/runtime/stageProcessLauncher.js

@@ -1,9 +1,10 @@
 import * as childProcess from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { logger as rootLogger, resolveLogMaxLineBytes, } from "../logging/logger.js";
+import { isCursorModelRef, readCursorApiKey } from "../agent/cursorProvider.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 { PI_HOME_AUTH_PATH_ENV, stageflowAgentAuthPath } from "./credentialBinding.js";
 import { redactString } from "../logging/redact.js";
 import { getNamedSecrets } from "../logging/namedSecrets.js";
 import { readMaxActiveStageProcesses, } from "./stageConcurrency.js";
@@ -11,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;
@@ -177,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" };
@@ -278,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",
@@ -338,11 +352,18 @@ export class StageProcessLauncher {
             : overlaid;
         const childEnv = {
             ...withBrowser,
-            [PI_HOME_AUTH_PATH_ENV]: piHomeAuthPath(),
+            [PI_HOME_AUTH_PATH_ENV]: stageflowAgentAuthPath(),
         };
+        const cursorApiKey = readCursorApiKey(hostEnv);
+        if (isCursorModelRef(input.model ?? "") &&
+            cursorApiKey !== undefined &&
+            cursorApiKey !== "" &&
+            childEnv.CURSOR_API_KEY === undefined) {
+            childEnv.CURSOR_API_KEY = cursorApiKey;
+        }
         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.
@@ -380,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;
     /**