stageflow 0.30.0 → 0.32.0

package/dist/agent/cursorProvider.d.ts

@@ -1,7 +1,15 @@
 import { type StageProviderSupport } from "./providerSupport.js";
 export declare function cursorExtensionEntryInPackage(packageRoot: string): string | undefined;
+export declare function resolveBundledCursorExtensionPath(): string | undefined;
+/** `$STAGEFLOW_HOME/agent/npm` install (Pi-style); after bundled dependency. */
+export declare function resolveAgentHomeCursorExtensionPath(): string | undefined;
 export declare function resolveCursorExtensionPath(): string | undefined;
 export declare function isCursorModelRef(modelRef: string): boolean;
 export declare function workshopCursorBridgeHint(toolNames: readonly string[]): string;
 export declare function cursorBridgePrompt(message: string, modelId: string | undefined, toolNames: readonly string[]): string;
 export declare const cursorProviderSupport: StageProviderSupport;
+export declare function readCursorApiKey(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getCursorHostStatus(env?: NodeJS.ProcessEnv): {
+    cursorSdkReady: boolean;
+    cursorApiKeyConfigured: boolean;
+};

package/dist/agent/cursorProvider.js

@@ -5,10 +5,13 @@
  * module's prepare()/env sealing path.
  */
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { readSecretFromEnvOrFile } from "../config/secretFromEnvOrFile.js";
+import { globalStageflowHome } from "../project/globalHome.js";
 import { registerProviderSupport, } from "./providerSupport.js";
+import { stageflowAgentAuthPath } from "../runtime/credentialBinding.js";
 const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
 /**
  * Locate the pi-cursor-sdk extension entry without opening full global package
@@ -17,21 +20,18 @@ const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
  * Resolution order:
  * 1. STAGEFLOW_CURSOR_EXTENSION (absolute path to the extension .ts/.js)
  * 2. Path package from the Pi agent settings.json (same source interactive pi uses)
- * 3. npm install under <pi-agent>/npm/node_modules/pi-cursor-sdk
+ * 3. npm dependency `pi-cursor-sdk` bundled with the Stageflow install (repo or global)
+ * 4. npm install under <stageflow-agent>/npm/node_modules/pi-cursor-sdk
  *    (`dist/index.js` for 0.3+, `src/index.ts` for older publishes)
- * 4. Sibling checkout at ../pi-cursor-sdk relative to this repo
+ * 5. Sibling checkout at ../pi-cursor-sdk relative to this repo
  *
- * A stage worker's HOME is an empty attempt directory, so the Pi agent dir is
- * the directory of STAGEFLOW_PI_HOME_AUTH_PATH when the Host set it, not
- * os.homedir().
+ * A stage worker's HOME is an empty attempt directory; the agent dir comes from
+ * STAGEFLOW_AGENT_AUTH_PATH when the Host set it.
  */
 const CURSOR_PACKAGE_ENTRIES = ["dist/index.js", "src/index.ts"];
-/** Pi agent dir. Stage workers must not use os.homedir(): HOME is the attempt dir. */
+/** Stageflow agent dir ($STAGEFLOW_HOME/agent). Stage workers must not use os.homedir(): HOME is the attempt dir. */
 function piAgentDir() {
-    const auth = process.env.STAGEFLOW_PI_HOME_AUTH_PATH?.trim();
-    if (auth)
-        return path.dirname(path.resolve(auth));
-    return path.join(os.homedir(), ".pi", "agent");
+    return path.dirname(stageflowAgentAuthPath());
 }
 export function cursorExtensionEntryInPackage(packageRoot) {
     for (const rel of CURSOR_PACKAGE_ENTRIES) {
@@ -42,6 +42,21 @@ export function cursorExtensionEntryInPackage(packageRoot) {
     }
     return undefined;
 }
+export function resolveBundledCursorExtensionPath() {
+    const require = createRequire(import.meta.url);
+    let packageRoot;
+    try {
+        packageRoot = path.dirname(require.resolve("pi-cursor-sdk/package.json"));
+    }
+    catch {
+        return undefined;
+    }
+    return cursorExtensionEntryInPackage(packageRoot);
+}
+/** `$STAGEFLOW_HOME/agent/npm` install (Pi-style); after bundled dependency. */
+export function resolveAgentHomeCursorExtensionPath() {
+    return cursorExtensionEntryInPackage(path.join(piAgentDir(), "npm", "node_modules", "pi-cursor-sdk"));
+}
 export function resolveCursorExtensionPath() {
     const fromEnv = process.env.STAGEFLOW_CURSOR_EXTENSION?.trim();
     if (fromEnv && existsSync(fromEnv)) {
@@ -51,7 +66,11 @@ export function resolveCursorExtensionPath() {
     if (fromSettings) {
         return fromSettings;
     }
-    const npmEntry = cursorExtensionEntryInPackage(path.join(piAgentDir(), "npm", "node_modules", "pi-cursor-sdk"));
+    const bundled = resolveBundledCursorExtensionPath();
+    if (bundled) {
+        return bundled;
+    }
+    const npmEntry = resolveAgentHomeCursorExtensionPath();
     if (npmEntry) {
         return npmEntry;
     }
@@ -78,7 +97,7 @@ function sealCursorSettingSources() {
 function missingExtensionReason(modelRef) {
     return [
         `Model "${modelRef}" requires pi-cursor-sdk, but no extension entry was found.`,
-        "Install with `pi install npm:pi-cursor-sdk`, or set STAGEFLOW_CURSOR_EXTENSION",
+        `Install Stageflow with npm (includes pi-cursor-sdk), or set STAGEFLOW_CURSOR_EXTENSION`,
         "to the absolute path of pi-cursor-sdk/dist/index.js (or src/index.ts).",
         "Also ensure a Cursor SDK API key is available via Pi /login or CURSOR_API_KEY.",
     ].join(" ");
@@ -122,6 +141,37 @@ export const cursorProviderSupport = {
         ].join(" ");
     },
 };
+const CURSOR_API_KEY_FILE_NAME = "cursor-api-key";
+export function readCursorApiKey(env = process.env) {
+    let fromEnv;
+    try {
+        fromEnv = readSecretFromEnvOrFile(env, "CURSOR_API_KEY");
+    }
+    catch {
+        return undefined;
+    }
+    if (fromEnv !== undefined && fromEnv.trim() !== "") {
+        return fromEnv.trim();
+    }
+    const filePath = path.join(globalStageflowHome(), "agent", CURSOR_API_KEY_FILE_NAME);
+    if (!existsSync(filePath)) {
+        return undefined;
+    }
+    try {
+        const raw = readFileSync(filePath, "utf8").replace(/\r?\n$/, "").trim();
+        return raw.length > 0 ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getCursorHostStatus(env = process.env) {
+    const key = readCursorApiKey(env);
+    return {
+        cursorSdkReady: resolveCursorExtensionPath() !== undefined,
+        cursorApiKeyConfigured: key !== undefined,
+    };
+}
 registerProviderSupport(cursorProviderSupport);
 function resolveFromPiSettings() {
     const agentDir = piAgentDir();

package/dist/agent/piAdapter.js

@@ -44,6 +44,9 @@ import { attemptContext, noAttemptContext, } from "../runtime/stageAttemptContex
 import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
 import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
+import { createSendEmailTool } from "../tools/sendEmail.js";
+import { createReplyEmailTool } from "../tools/replyEmail.js";
+import { createGetEmailTool, createSearchEmailTool, createDownloadEmailAttachmentTool } from "../tools/readEmail.js";
 import "./cursorProvider.js";
 import { findProviderSupport } from "./providerSupport.js";
 import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
@@ -479,6 +482,9 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             ].join("\n")
             : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
     return [
+        ...(input.stage.email?.length ? [
+            `Stageflow email permissions: ${JSON.stringify(input.stage.email)}. Use only declared accounts and operations. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
+        ] : []),
         `Task id: ${input.task.id}`,
         `Stage id: ${runtimeStageId(input)}`,
         `Goal: ${input.task.goal}`,
@@ -908,6 +914,21 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         if (attached.extensionFactories !== undefined) {
             tools.push(...collectMcpExtensionToolNames(loader));
         }
+        if (input.email) {
+            const permitted = new Set(input.stage.email?.flatMap(permission => permission.operations));
+            const definitions = [
+                permitted.has("send") ? createSendEmailTool(input.email) : undefined,
+                permitted.has("reply") ? createReplyEmailTool(input.email) : undefined,
+                permitted.has("search") ? createSearchEmailTool(input.email) : undefined,
+                permitted.has("getMessage") ? createGetEmailTool(input.email) : undefined,
+                permitted.has("downloadAttachment") ? createDownloadEmailAttachmentTool(input.email) : undefined,
+            ];
+            for (const definition of definitions)
+                if (definition) {
+                    customTools.push(defineTool(definition));
+                    tools.push(definition.name);
+                }
+        }
         return {
             sessionManager,
             modelRuntime,

package/dist/agent/port.d.ts

@@ -7,6 +7,7 @@ import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
 import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
+import type { StageEmail } from "../email/host.js";
 import type { QaExchange } from "../hitl/qaTrail.js";
 import type { StageUsage } from "../types/usage.js";
 /** Opaque to runtime; adapters interpret. */
@@ -63,6 +64,7 @@ export type StageRunInput = {
     /** Optional raw assistant-text-delta sink, fired alongside onActivity, not instead of it. */
     onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
+    email?: StageEmail;
     /** Bundled browser skill; set by the runtime when the stage has `browser`. */
     browserSkillFilePath?: string;
     forkEmitContext?: ForkEmitContext;

package/dist/agent/providerAuth.d.ts

@@ -25,12 +25,16 @@ export type ProvidersListResult = {
     via: "pi";
     providers: ProviderSummary[];
 };
-export type PiHomeDetectResult = {
-    piHomeUsable: boolean;
+export type ProvidersDetectResult = {
     credentialSource?: CredentialSource;
     provisional: boolean;
     source: CredentialSource;
+    authConfigured: boolean;
+    cursorSdkReady: boolean;
+    cursorApiKeyConfigured: boolean;
 };
+/** @deprecated Use ProvidersDetectResult */
+export type PiHomeDetectResult = ProvidersDetectResult;
 export type ProviderAuthRuntime = {
     getProviders(): readonly Provider[];
     getProvider(providerId: string): Provider | undefined;
@@ -84,7 +88,7 @@ export type OauthLoginResult = {
 };
 export declare function loginWithOauth(cwd: string, providerId: string, interaction: AuthInteraction, ctx?: ProviderAuthContext): Promise<OauthLoginResult>;
 export declare function logoutProvider(cwd: string, providerId: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus>;
-export declare function detectPiHome(cwd: string): PiHomeDetectResult;
+export declare function detectPiHome(cwd: string): ProvidersDetectResult;
 export declare function getCredentialSourceSettings(cwd: string): {
     credentialSource?: CredentialSource;
     binding: {

package/dist/agent/providerAuth.js

@@ -1,5 +1,6 @@
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
-import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, resolveCredentialBinding, writeCredentialSourceToContext, } from "../runtime/credentialBinding.js";
+import { parseCredentialSource, resolveCredentialBinding, writeCredentialSourceToContext, isUsableAuthFile, } from "../runtime/credentialBinding.js";
+import { getCursorHostStatus } from "./cursorProvider.js";
 import { readPersistedCredentialSourceFromContext, } from "../runtime/settingsFile.js";
 import { resolveProjectContext } from "../project/resolveProjectContext.js";
 export function makeMutationLock() {
@@ -251,10 +252,11 @@ export function detectPiHome(cwd) {
     const binding = resolveCredentialBinding(projectCtx);
     const persisted = readPersistedCredentialSourceFromContext(projectCtx);
     return {
-        piHomeUsable: isUsableAuthFile(piHomeAuthPath()),
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
         provisional: binding.provisional,
         source: binding.source,
+        authConfigured: isUsableAuthFile(binding.authPath),
+        ...getCursorHostStatus(),
     };
 }
 export function getCredentialSourceSettings(cwd) {
@@ -272,7 +274,7 @@ export function getCredentialSourceSettings(cwd) {
 export function setCredentialSource(cwd, credentialSource) {
     const parsed = parseCredentialSource(credentialSource);
     if (parsed === undefined) {
-        throw new ProviderAuthError('credentialSource must be "pi_home" or "sf_owned"', 400);
+        throw new ProviderAuthError('credentialSource must be "sf_owned"', 400);
     }
     const projectCtx = resolveProjectContext(cwd);
     writeCredentialSourceToContext(projectCtx, parsed);

package/dist/cli/doctorCommand.js

@@ -215,6 +215,13 @@ async function freeDiskCheck(home, env) {
         const size = await readFilesystemSize(home);
         const floor = resolveMinFreeDiskFloor(env.STAGEFLOW_MIN_FREE_DISK_BYTES, size.totalBytes);
         const freeGiB = (size.freeBytes / (1024 * 1024 * 1024)).toFixed(2);
+        if (floor === 0) {
+            return {
+                id: "free_disk",
+                status: "pass",
+                message: `${home} has ${freeGiB} GiB free (free-disk admission disabled)`,
+            };
+        }
         if (size.freeBytes < floor) {
             return {
                 id: "free_disk",

package/dist/cli/providersCommand.d.ts

@@ -1,6 +1,6 @@
 import type { AuthInteraction } from "@earendil-works/pi-ai";
 import { type ProviderAuthContext } from "../agent/providerAuth.js";
-export declare const PROVIDERS_USAGE = "Usage:\n  sf providers list\n  sf providers status [--provider <id>]\n  sf providers detect\n  sf providers source [get | set <pi_home|sf_owned>]\n  sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]\n  sf providers logout <providerId>";
+export declare const PROVIDERS_USAGE = "Usage:\n  sf providers list\n  sf providers status [--provider <id>]\n  sf providers detect\n  sf providers source [get | set sf_owned]\n  sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]\n  sf providers logout <providerId>";
 export type ProvidersCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/providersCommand.js

@@ -6,7 +6,7 @@ export const PROVIDERS_USAGE = `Usage:
   sf providers list
   sf providers status [--provider <id>]
   sf providers detect
-  sf providers source [get | set <pi_home|sf_owned>]
+  sf providers source [get | set sf_owned]
   sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]
   sf providers logout <providerId>`;
 const defaultIo = {
@@ -167,7 +167,7 @@ export async function runProvidersCommand(args, cwd, io = {}, ctx = defaultConte
                     ? `credentialSource=${detected.credentialSource}`
                     : "credentialSource=(unset)";
                 out.log([
-                    `piHomeUsable=${detected.piHomeUsable}`,
+                    `authConfigured=${detected.authConfigured}`,
                     sourceLine,
                     `provisional=${detected.provisional}`,
                     `bindingSource=${detected.source}`,
@@ -188,8 +188,8 @@ export async function runProvidersCommand(args, cwd, io = {}, ctx = defaultConte
                 }
                 if (action === "set") {
                     const value = parsed.positionals[1];
-                    if (value !== "pi_home" && value !== "sf_owned") {
-                        out.error('source set requires pi_home or sf_owned');
+                    if (value !== "sf_owned") {
+                        out.error('source set requires sf_owned');
                         out.error(PROVIDERS_USAGE);
                         return 1;
                     }

package/dist/cli.js

@@ -69,7 +69,7 @@ const USAGE = `Usage:
   sf providers list
   sf providers status [--provider <id>]
   sf providers detect
-  sf providers source [get | set <pi_home|sf_owned>]
+  sf providers source [get | set sf_owned]
   sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]
   sf providers logout <providerId>
   sf skills list

package/dist/config/loadStage.js

@@ -7,6 +7,7 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { z } from "zod";
 import { parseStageSecrets } from "../runtime/stageSecretDecl.js";
 import { parseToolRequires } from "./toolRequires.js";
 import { parseStageBrowser } from "./stageBrowser.js";
@@ -140,6 +141,15 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compi
         id: entryId,
         system_prompt: raw.system_prompt,
     };
+    if (raw.email !== undefined) {
+        const permissions = z.array(z.object({ accountId: z.string().min(1).max(200),
+            operations: z.array(z.enum(["send", "reply", "getMessage", "search", "downloadAttachment"])).min(1).max(5),
+        }).strict()).max(20).safeParse(raw.email);
+        if (!permissions.success || new Set(permissions.data.map(permission => permission.accountId)).size !== permissions.data.length) {
+            return loadFailure([{ code: "stage.invalid_shape", message: `Invalid stage ${label}: invalid email permissions`, category: "stage", stageId: entryId }]);
+        }
+        stage.email = permissions.data;
+    }
     if (raw.clone_actions !== undefined) {
         return loadFailure([
             {

package/dist/config/pipelineStageKeys.js

@@ -28,6 +28,7 @@ export const WIRING_KEYS = new Set([
 ]);
 /** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export const BODY_KEYS = new Set([
+    "email",
     "system_prompt",
     "model",
     "payload_schema",

package/dist/email/accounts.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { type EmailAccountStatus } from "./port.js";
+declare const connectionSchema: z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodNumber;
+    username: z.ZodString;
+    tls: z.ZodDefault<z.ZodEnum<{
+        implicit: "implicit";
+        none: "none";
+        starttls: "starttls";
+    }>>;
+    auth: z.ZodObject<{
+        type: z.ZodEnum<{
+            oauth2: "oauth2";
+            password: "password";
+        }>;
+        secretRef: z.ZodString;
+        expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const accountSchema: z.ZodObject<{
+    displayName: z.ZodString;
+    address: z.ZodEmail;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    adapter: z.ZodDefault<z.ZodLiteral<"local">>;
+    folders: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    senderAliases: z.ZodDefault<z.ZodArray<z.ZodEmail>>;
+    imap: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        username: z.ZodString;
+        tls: z.ZodDefault<z.ZodEnum<{
+            implicit: "implicit";
+            none: "none";
+            starttls: "starttls";
+        }>>;
+        auth: z.ZodObject<{
+            type: z.ZodEnum<{
+                oauth2: "oauth2";
+                password: "password";
+            }>;
+            secretRef: z.ZodString;
+            expiresAt: z.ZodOptional<z.ZodISODateTime>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    smtp: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        username: z.ZodString;
+        tls: z.ZodDefault<z.ZodEnum<{
+            implicit: "implicit";
+            none: "none";
+            starttls: "starttls";
+        }>>;
+        auth: z.ZodObject<{
+            type: z.ZodEnum<{
+                oauth2: "oauth2";
+                password: "password";
+            }>;
+            secretRef: z.ZodString;
+            expiresAt: z.ZodOptional<z.ZodISODateTime>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    allowInsecureLocalDevelopment: z.ZodDefault<z.ZodBoolean>;
+    connectionTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    pollingIntervalMs: z.ZodDefault<z.ZodNumber>;
+    reconnectMaxDelayMs: z.ZodDefault<z.ZodNumber>;
+    searchWorkLimit: z.ZodDefault<z.ZodNumber>;
+    attachmentLimits: z.ZodDefault<z.ZodObject<{
+        count: z.ZodDefault<z.ZodNumber>;
+        perFileBytes: z.ZodDefault<z.ZodNumber>;
+        totalBytes: z.ZodDefault<z.ZodNumber>;
+        downloadBytes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    sentFolder: z.ZodOptional<z.ZodString>;
+    sentCopyPolicy: z.ZodDefault<z.ZodEnum<{
+        "imap-append": "imap-append";
+        "provider-managed": "provider-managed";
+    }>>;
+    sentCopyMaxBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type EmailAccountInput = z.input<typeof accountSchema>;
+export type EmailConnection = z.output<typeof connectionSchema>;
+export type EmailAccount = z.output<typeof accountSchema> & {
+    accountId: string;
+    scope: string;
+};
+/** Host-owned configuration. Reads return copies; mutations replace the file atomically. */
+export declare class EmailAccounts {
+    readonly scope: string;
+    private readonly file;
+    private state;
+    private readonly listeners;
+    constructor(cwd: string);
+    list(): EmailAccount[];
+    get(accountId: string, requireEnabled?: boolean): EmailAccount;
+    create(input: unknown): EmailAccount;
+    update(accountId: string, patch: unknown): EmailAccount;
+    remove(accountId: string): void;
+    health(accountId: string): EmailAccountStatus | undefined;
+    recordHealth(status: EmailAccountStatus): void;
+    onChange(listener: (accountId: string) => void): () => void;
+    private notify;
+    private requireHttpAccount;
+    private syncStartupAccounts;
+    private persist;
+}
+export declare function resolveEmailSecret(connection: EmailConnection, env?: NodeJS.ProcessEnv): string;
+export {};