stageflow 0.31.0 → 0.33.0

package/README.md

@@ -254,6 +254,7 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 |-----|-------------|
 | [docs/README.md](docs/README.md) | Documentation index |
 | [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
+| [docs/hosted.md](docs/hosted.md) | Embed Stageflow from another application and receive ordered run events |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
 | [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf run-stage`, `sf graph`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |

package/dist/agent/fakeAgent.js

@@ -113,12 +113,6 @@ export class FakeAgent {
                 armWait();
             }
         }
-        if (sessionMode === "feedback_resume" && behavior.type === "wait_then_emit") {
-            behavior = {
-                type: "emit",
-                envelope: behavior.envelope,
-            };
-        }
         const emitStartActivity = () => {
             if (started)
                 return;

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

@@ -82,6 +82,12 @@ export declare function statusForProvider(runtime: ProviderAuthRuntime, provider
 export declare function listProviders(cwd: string, ctx?: ProviderAuthContext): Promise<ProvidersListResult>;
 export declare function getAuthStatus(cwd: string, providerId?: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus | ProviderAuthStatus[]>;
 export declare function loginWithApiKey(cwd: string, providerId: string, apiKey: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus>;
+/** Write a provider API key into an existing Pi auth file. Does not create the operator home. */
+export declare function configurePiProviderApiKey(options: {
+    authPath: string;
+    providerId: string;
+    apiKey: string;
+}, ctx?: ProviderAuthContext): Promise<void>;
 export type OauthLoginResult = {
     provider: ProviderAuthStatus;
     warning?: string;

package/dist/agent/providerAuth.js

@@ -1,3 +1,5 @@
+import { mkdir, writeFile, chmod, access } from "node:fs/promises";
+import path from "node:path";
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
 import { parseCredentialSource, resolveCredentialBinding, writeCredentialSourceToContext, isUsableAuthFile, } from "../runtime/credentialBinding.js";
 import { getCursorHostStatus } from "./cursorProvider.js";
@@ -22,6 +24,23 @@ export class ProviderAuthError extends Error {
     }
 }
 const defaultCreateRuntime = async (authPath) => ModelRuntime.create({ authPath, refreshOnCreate: false });
+async function ensurePiAuthFile(authPath) {
+    const resolved = path.resolve(authPath);
+    await mkdir(path.dirname(resolved), { recursive: true });
+    try {
+        await access(resolved);
+    }
+    catch {
+        await writeFile(resolved, "{}\n", { encoding: "utf8", mode: 0o600 });
+    }
+    try {
+        await chmod(resolved, 0o600);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return resolved;
+}
 export const defaultContext = {
     createRuntime: defaultCreateRuntime,
     lock: makeMutationLock(),
@@ -159,26 +178,43 @@ function mapLoginError(err, providerId) {
     }
     throw new ProviderAuthError("Provider login failed", 500);
 }
+async function loginApiKeyOnRuntime(runtime, providerId, apiKey) {
+    if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+        throw new ProviderAuthError("apiKey is required", 400);
+    }
+    const provider = runtime.getProvider(providerId);
+    if (!provider) {
+        throw new ProviderAuthError("Provider not found", 404);
+    }
+    if (typeof provider.auth.apiKey?.login !== "function") {
+        throw new ProviderAuthError("Provider does not support api_key login", 400);
+    }
+    try {
+        await runtime.login(providerId, "api_key", apiKeyInteraction(apiKey));
+    }
+    catch (err) {
+        mapLoginError(err, providerId);
+    }
+    return statusForProvider(runtime, providerId);
+}
 export async function loginWithApiKey(cwd, providerId, apiKey, ctx = defaultContext) {
     if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
         throw new ProviderAuthError("apiKey is required", 400);
     }
     return ctx.lock.withMutationLock(async () => {
         const runtime = await openRuntime(cwd, ctx);
-        const provider = runtime.getProvider(providerId);
-        if (!provider) {
-            throw new ProviderAuthError("Provider not found", 404);
-        }
-        if (typeof provider.auth.apiKey?.login !== "function") {
-            throw new ProviderAuthError("Provider does not support api_key login", 400);
-        }
-        try {
-            await runtime.login(providerId, "api_key", apiKeyInteraction(apiKey));
-        }
-        catch (err) {
-            mapLoginError(err, providerId);
-        }
-        return statusForProvider(runtime, providerId);
+        return loginApiKeyOnRuntime(runtime, providerId, apiKey);
+    });
+}
+/** Write a provider API key into an existing Pi auth file. Does not create the operator home. */
+export async function configurePiProviderApiKey(options, ctx = defaultContext) {
+    if (typeof options.authPath !== "string" || options.authPath.trim() === "") {
+        throw new ProviderAuthError("authPath is required", 400);
+    }
+    const authPath = await ensurePiAuthFile(options.authPath);
+    await ctx.lock.withMutationLock(async () => {
+        const runtime = await ctx.createRuntime(authPath);
+        await loginApiKeyOnRuntime(runtime, options.providerId, options.apiKey);
     });
 }
 export async function loginWithOauth(cwd, providerId, interaction, ctx = defaultContext) {

package/dist/agent/resolveAgentPort.d.ts

@@ -11,6 +11,8 @@ export type AgentSelection = {
 };
 /** stage > pipeline > global > "pi", with stage gated off for now. */
 export declare function resolveAgentBackend(selection?: AgentSelection): AgentBackendId;
+/** Existing Pi AgentPort. Hosted runs pass this into createHostedRuntime. */
+export declare function createPiAgentPort(): AgentPort;
 export declare function resolveAgentPort(selection?: AgentSelection): AgentPort;
 /** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
 export declare function globalAgentBackendFromManifest(manifest: LoadedManifest | null): AgentBackendId | undefined;

package/dist/agent/resolveAgentPort.js

@@ -9,11 +9,15 @@ export function resolveAgentBackend(selection = {}) {
     }
     return selection.pipeline ?? selection.global ?? "pi";
 }
+/** Existing Pi AgentPort. Hosted runs pass this into createHostedRuntime. */
+export function createPiAgentPort() {
+    return new PiAgentAdapter();
+}
 export function resolveAgentPort(selection = {}) {
     const backend = resolveAgentBackend(selection);
     switch (backend) {
         case "pi":
-            return new PiAgentAdapter();
+            return createPiAgentPort();
         case "claude":
             return new ClaudeAgentAdapter();
     }

package/dist/config/listConfig.d.ts

@@ -1,28 +1,12 @@
-import type { StageGateKind } from "../types/stage.js";
 import type { LoadedManifest } from "../types/stageflowManifest.js";
 import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
 import { type StageflowContext } from "../project/resolveStageflowContext.js";
 import { type CatalogContext } from "./resolveCatalogContext.js";
 export type { PipelineListing, PipelineStageListing, TaskListing } from "./browseCatalog.js";
-export type ValidStageListing = {
-    path: string;
-    id: string;
-    used_by_pipeline_ids: string[];
-    gate_kinds?: StageGateKind[];
-};
-export type BrokenStageListing = {
-    path: string;
-    error: string;
-    id?: string;
-    model?: string;
-    gate_kinds?: StageGateKind[];
-};
-export type StageListing = ValidStageListing | BrokenStageListing;
 export type CatalogListOptions = {
     projectRoot: string;
     manifest: LoadedManifest;
 };
 export declare function listTasks(options: CatalogListOptions): Promise<TaskListing[]>;
 export declare function listPipelines(options: CatalogListOptions): Promise<PipelineListing[]>;
-export declare function listStages(_options?: unknown): Promise<StageListing[]>;
 export declare function listModels(cwdOrContext: string | CatalogContext | StageflowContext): Promise<string[]>;

package/dist/config/listConfig.js

@@ -17,9 +17,6 @@ export async function listPipelines(options) {
         issues: [],
     });
 }
-export async function listStages(_options) {
-    return [];
-}
 export async function listModels(cwdOrContext) {
     const ctx = typeof cwdOrContext === "string"
         ? catalogContextFromStageflow(await resolveStageflowContext(cwdOrContext))

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 {};