stageflow 0.32.0 → 0.35.0

package/README.md

@@ -2,7 +2,7 @@
 
 Open-source runtime for **configurable multi-stage agent workflows** with typed handoffs, DAG execution, human gates, MCP, CI, and a local operator console.
 
-[![Site](https://stage-flow.dev)](stage-flow.dev)
+[![Website](https://img.shields.io/badge/website-stage--flow.dev-111111)](https://stage-flow.dev)
 [![npm version](https://img.shields.io/npm/v/stageflow)](https://www.npmjs.com/package/stageflow)
 [![npm downloads](https://img.shields.io/npm/dm/stageflow)](https://www.npmjs.com/package/stageflow)
 ![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)
@@ -46,7 +46,7 @@ The same pipeline runs three ways without rewriting anything:
 
 ![Stageflow architecture: pipeline definitions and operator interfaces drive the orchestration runtime, which coordinates agent execution and persisted state](docs/img/stageflow-architecture.svg)
 
-The scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out/join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind `AgentPort`; Pi supplies the current coding-agent session, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI.
+The scheduler owns orchestration semantics: DAG readiness, bounded parallelism, fan-out/join, conditional routing, retries, skipped branches, and resumable human gates. Agent execution sits behind `StagePort`; Pi supplies the current coding-agent session, while Stageflow owns pipeline state, stage workspaces, handoff validation, and the interfaces used by the CLI, console, MCP, and CI.
 
 See [Architecture](docs/architecture.md) for component boundaries, execution flow, persistence, recovery behavior, and the tradeoffs behind fresh sessions and explicit handoffs.
 
@@ -101,7 +101,7 @@ sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
 
 Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
-**Docker Compose** (UI + MCP in one Host): copy [`.env.example`](.env.example) → `.env`, set `STAGEFLOW_CONTROL_TOKEN`, then `docker compose up --build -d`. Checklist: [docs/docker.md](docs/docker.md#local-try-compose).
+**Docker Compose** (UI + MCP in one Host): copy [`.env.example`](.env.example) → `.env`, then `docker compose up --build -d`. The shipped compose file publishes port 3847 on localhost only and does not require a control token. Checklist: [docs/docker.md](docs/docker.md#local-try-compose).
 
 ## Connect a model provider
 
@@ -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/adapterSpill.d.ts

@@ -0,0 +1,14 @@
+export type AdapterSpill = {
+    kind: "none";
+} | {
+    kind: "full";
+    text: string;
+    sourcePath: string;
+} | {
+    kind: "lost";
+    reason: string;
+};
+export declare function acceptedAdapterSpillPath(candidate: string): Promise<string | undefined>;
+export declare function readAdapterSpill(text: string, details: unknown): Promise<AdapterSpill>;
+/** Removes a vetted spill file and its now-empty `pi-mcp-output-*` dir. */
+export declare function discardAdapterSpill(sourcePath: string): Promise<void>;

package/dist/agent/adapterSpill.js

@@ -0,0 +1,83 @@
+/**
+ * pi-mcp-adapter cuts MCP text output at its output-guard limit and writes the
+ * full text to `<tmpdir>/pi-mcp-output-*\/output-<hex>.txt`. When that happens
+ * the visible result is only a head preview, so the tool output budget reads
+ * the full body from the spill file instead. Only real files inside the OS
+ * temp dir with the adapter's naming are accepted.
+ */
+import { lstat, readFile, realpath, rmdir, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+const SPILL_DIR = /^pi-mcp-output-[A-Za-z0-9]+$/;
+const SPILL_FILE = /^output-[0-9a-f]{8}\.txt$/;
+const SAVED_NOTICE = /Full text saved to: (\S+) —/;
+function outputGuardOf(details) {
+    if (details === null || typeof details !== "object")
+        return undefined;
+    const guard = details.outputGuard;
+    return guard !== null && typeof guard === "object"
+        ? guard
+        : undefined;
+}
+export async function acceptedAdapterSpillPath(candidate) {
+    if (candidate.includes("\0") || !path.isAbsolute(candidate))
+        return undefined;
+    let real;
+    try {
+        const linked = await lstat(candidate);
+        if (!linked.isFile() && !linked.isSymbolicLink())
+            return undefined;
+        real = await realpath(candidate);
+        if (!(await lstat(real)).isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const tempRoot = await realpath(tmpdir());
+    if (!isInsideDir(real, tempRoot))
+        return undefined;
+    if (!SPILL_DIR.test(path.basename(path.dirname(real))))
+        return undefined;
+    if (!SPILL_FILE.test(path.basename(real)))
+        return undefined;
+    return real;
+}
+export async function readAdapterSpill(text, details) {
+    const guard = outputGuardOf(details);
+    if (guard?.truncated !== true) {
+        return { kind: "none" };
+    }
+    const candidates = [
+        typeof guard?.fullOutputPath === "string" ? guard.fullOutputPath : undefined,
+        SAVED_NOTICE.exec(text)?.[1],
+    ].filter((candidate) => candidate !== undefined);
+    for (const candidate of new Set(candidates)) {
+        const source = await acceptedAdapterSpillPath(candidate);
+        if (source === undefined)
+            continue;
+        try {
+            return { kind: "full", text: await readFile(source, "utf8"), sourcePath: source };
+        }
+        catch {
+            continue;
+        }
+    }
+    return {
+        kind: "lost",
+        reason: typeof guard?.writeError === "string"
+            ? guard.writeError
+            : "the MCP adapter's full-output file was not available",
+    };
+}
+/** Removes a vetted spill file and its now-empty `pi-mcp-output-*` dir. */
+export async function discardAdapterSpill(sourcePath) {
+    try {
+        await unlink(sourcePath);
+        await rmdir(path.dirname(sourcePath));
+    }
+    catch {
+        // best-effort cleanup
+    }
+}

package/dist/agent/agentBackend.d.ts

@@ -1,5 +1,5 @@
 /**
- * Known AgentPort backend ids, and the config-hierarchy gate.
+ * Known StagePort backend ids, and the config-hierarchy gate.
  *
  * Kept dependency-free (no adapter imports) so config loaders can validate
  * `agent:` fields without pulling in the actual SDKs.
@@ -25,7 +25,7 @@ export type ParsedAgentField = {
 export declare function parseAgentField(raw: unknown): ParsedAgentField;
 /**
  * Stage-level `agent` overrides are parsed and stored on StageConfig, but
- * intentionally not consulted by resolveAgentBackend while this is false.
+ * intentionally not consulted by resolveStageBackend while this is false.
  * Flip to true once per-stage selection is ready to ship; no other change
  * needed to light it up.
  */

package/dist/agent/agentBackend.js

@@ -1,5 +1,5 @@
 /**
- * Known AgentPort backend ids, and the config-hierarchy gate.
+ * Known StagePort backend ids, and the config-hierarchy gate.
  *
  * Kept dependency-free (no adapter imports) so config loaders can validate
  * `agent:` fields without pulling in the actual SDKs.
@@ -31,7 +31,7 @@ export function parseAgentField(raw) {
 }
 /**
  * Stage-level `agent` overrides are parsed and stored on StageConfig, but
- * intentionally not consulted by resolveAgentBackend while this is false.
+ * intentionally not consulted by resolveStageBackend while this is false.
  * Flip to true once per-stage selection is ready to ship; no other change
  * needed to light it up.
  */

package/dist/agent/claudeAdapter.d.ts

@@ -1,5 +1,16 @@
-import { type AgentPort, type StageHandle, type StageRunInput, type StageRunResult } from "./port.js";
-export declare class ClaudeAgentAdapter implements AgentPort {
+import { type StagePort, type StageHandle, type StageRunInput, type StageRunResult } from "./port.js";
+/**
+ * Provider error carried by a query() `result` message: an API error on a "success" result
+ * (`is_error` with the error text in `result`) or an error subtype with `errors`.
+ */
+export declare function claudeResultError(message: {
+    subtype?: unknown;
+    is_error?: unknown;
+    result?: unknown;
+    errors?: unknown;
+    api_error_status?: unknown;
+}): string | undefined;
+export declare class ClaudeAgentAdapter implements StagePort {
     openStage(input: StageRunInput): StageHandle;
     runStage(input: StageRunInput): Promise<StageRunResult>;
 }

package/dist/agent/claudeAdapter.js

@@ -1,5 +1,5 @@
 /**
- * Claude Agent SDK implementation of AgentPort.
+ * Claude Agent SDK implementation of StagePort.
  *
  * One turn = one streaming-input `query()` call, spawned as a subprocess by
  * the SDK. The session is sealed the same way Pi's sealed stage session is:
@@ -43,6 +43,7 @@ import { isAdvancingEnvelope } from "../envelope/check.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, summarizeAnswer, } from "../tools/askOperator.js";
 import { buildStageflowMcpServer, EMIT_STAGE_ENVELOPE_TOOL_NAME, STAGEFLOW_MCP_SERVER_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME, ASK_OPERATOR_TOOL_NAME, } from "./claudeTools.js";
 import { createClaudeActivityMapper } from "./claudeActivity.js";
+import { DEFAULT_EMIT_REMINDERS, emitReminderPrompt, formatProviderError } from "./stageTurnDriver.js";
 import { readActivityVerbose } from "./activity.js";
 import { composeStageUserPrompt } from "./piAdapter.js";
 import { claudeSessionMarkerPath, clearClaudeSessionMarker, readClaudeSessionMarker, writeClaudeSessionMarker, } from "./claudeSession.js";
@@ -79,7 +80,10 @@ function preflight(input) {
     }
     return resolveClaudeModel(input.stage.model);
 }
-function resultFromCapture(capture) {
+function resultFromCapture(capture, providerError) {
+    if (providerError !== undefined && !capture.envelope) {
+        return { ok: false, reason: `provider error: ${providerError}` };
+    }
     if (capture.error && !capture.envelope) {
         return { ok: false, reason: capture.error };
     }
@@ -105,6 +109,20 @@ function failedPassedMcpConnect(resolved, listed) {
     }
     return undefined;
 }
+/**
+ * Provider error carried by a query() `result` message: an API error on a "success" result
+ * (`is_error` with the error text in `result`) or an error subtype with `errors`.
+ */
+export function claudeResultError(message) {
+    if (message.subtype === "success") {
+        if (message.is_error !== true)
+            return undefined;
+        const status = typeof message.api_error_status === "number" ? ` (HTTP ${message.api_error_status})` : "";
+        return formatProviderError(`${typeof message.result === "string" ? message.result : ""}${status}`);
+    }
+    const errors = Array.isArray(message.errors) ? message.errors.filter((e) => typeof e === "string") : [];
+    return formatProviderError(errors.length > 0 ? errors.join("; ") : String(message.subtype ?? "error"));
+}
 /** Merge one query() call's per-model totals (this call's own turns only) into the stage-level accumulator. */
 function mergeClaudeModelUsage(usage, modelUsage) {
     if (!modelUsage)
@@ -184,6 +202,7 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
     input.onActivity?.({ event: "agent_start" });
     input.onActivity?.({ event: "turn_start" });
     let sessionId = resumeSessionId;
+    let providerError;
     try {
         const mcpServer = buildStageflowMcpServer({
             capture: emitCapture,
@@ -266,6 +285,7 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
                     console.error(`[claudeAdapter] main loop saw result: modelUsage=${JSON.stringify(message.modelUsage)}`);
                 }
                 mergeClaudeModelUsage(usage, message.modelUsage);
+                providerError = claudeResultError(message);
                 break;
             }
         }
@@ -285,7 +305,14 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
             return { kind: "waiting", sessionId: resolvedSessionId, request: askCapture.prompt };
         }
         await clearClaudeSessionMarker(markerPath);
-        return { kind: "completed", result: { ...resultFromCapture(emitCapture), usage } };
+        const remind = emitCapture.envelope === undefined && providerError === undefined && sessionId !== undefined
+            ? { sessionId, ...(emitCapture.error !== undefined ? { rejectedEmit: emitCapture.error } : {}) }
+            : undefined;
+        return {
+            kind: "completed",
+            result: { ...resultFromCapture(emitCapture, providerError), usage },
+            ...(remind !== undefined ? { remind } : {}),
+        };
     }
     catch (err) {
         if (askCapture.prompt !== undefined && sessionId !== undefined) {
@@ -350,6 +377,23 @@ export class ClaudeAgentAdapter {
         let waiting;
         let pendingAnswer;
         const usage = emptyStageUsage();
+        /**
+         * While a turn ends on its own without an envelope, resume the same session with a short
+         * reminder turn, up to DEFAULT_EMIT_REMINDERS times. A reminder turn may itself park on
+         * ask_operator; a closed handle stops the loop.
+         */
+        const withEmitReminders = async (first, model) => {
+            let outcome = first;
+            for (let attempt = 1; attempt <= DEFAULT_EMIT_REMINDERS; attempt++) {
+                if (closed || outcome.kind !== "completed" || outcome.remind === undefined)
+                    break;
+                const reminder = emitReminderPrompt(EMIT_STAGE_ENVELOPE_TOOL_NAME, attempt, DEFAULT_EMIT_REMINDERS, outcome.remind.rejectedEmit);
+                // The Claude activity mapper does not echo prompts; show the reminder like Pi does.
+                input.onActivity?.({ event: "message", role: "user", text: reminder });
+                outcome = await runTurn(input, model, markerPath, reminder, outcome.remind.sessionId, usage);
+            }
+            return outcome;
+        };
         const applyOutcome = (outcome) => {
             if (outcome.kind === "waiting") {
                 waiting = { sessionId: outcome.sessionId, prompt: outcome.request };
@@ -403,7 +447,7 @@ export class ClaudeAgentAdapter {
                         return { status: "completed", result: { ok: false, reason: pre.reason } };
                     }
                     const outcome = await runTurn(input, pre.model, markerPath, resumePromptText(parsedAnswer), sessionId, usage);
-                    return applyOutcome(outcome);
+                    return applyOutcome(await withEmitReminders(outcome, pre.model));
                 }
                 const pre = preflight(input);
                 if (!pre.ok) {
@@ -421,10 +465,10 @@ export class ClaudeAgentAdapter {
                         };
                     }
                     const outcome = await runTurn(input, pre.model, markerPath, composeTimeoutResumePrompt(), marker.sessionId, usage);
-                    return applyOutcome(outcome);
+                    return applyOutcome(await withEmitReminders(outcome, pre.model));
                 }
                 const outcome = await runTurn(input, pre.model, markerPath, composeStageUserPrompt(input, EMIT_STAGE_ENVELOPE_TOOL_NAME, undefined, WRITE_STAGE_ARTIFACT_TOOL_NAME), undefined, usage);
-                return applyOutcome(outcome);
+                return applyOutcome(await withEmitReminders(outcome, pre.model));
             },
             deliverAnswer(answer) {
                 pendingAnswer = answer;

package/dist/agent/cursorProvider.d.ts

@@ -8,6 +8,9 @@ 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 cursorCredentialMissingReason(): string;
+/** Publish the credential-root Cursor key onto the process for a cursor/* model. */
+export declare function bindCursorApiKey(modelId: string): (() => void) | undefined;
 export declare function readCursorApiKey(env?: NodeJS.ProcessEnv): string | undefined;
 export declare function getCursorHostStatus(env?: NodeJS.ProcessEnv): {
     cursorSdkReady: boolean;

package/dist/agent/cursorProvider.js

@@ -9,9 +9,8 @@ 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 { globalCredentialRoot, 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
@@ -25,13 +24,13 @@ const CURSOR_SETTING_SOURCES_ENV = "PI_CURSOR_SETTING_SOURCES";
  *    (`dist/index.js` for 0.3+, `src/index.ts` for older publishes)
  * 5. Sibling checkout at ../pi-cursor-sdk relative to this repo
  *
- * A stage worker's HOME is an empty attempt directory; the agent dir comes from
- * STAGEFLOW_AGENT_AUTH_PATH when the Host set it.
+ * A stage worker's HOME is an empty attempt directory. Package lookup uses
+ * $STAGEFLOW_HOME/agent, not the credential root.
  */
 const CURSOR_PACKAGE_ENTRIES = ["dist/index.js", "src/index.ts"];
 /** Stageflow agent dir ($STAGEFLOW_HOME/agent). Stage workers must not use os.homedir(): HOME is the attempt dir. */
 function piAgentDir() {
-    return path.dirname(stageflowAgentAuthPath());
+    return path.join(globalStageflowHome(), "agent");
 }
 export function cursorExtensionEntryInPackage(packageRoot) {
     for (const rel of CURSOR_PACKAGE_ENTRIES) {
@@ -142,6 +141,24 @@ export const cursorProviderSupport = {
     },
 };
 const CURSOR_API_KEY_FILE_NAME = "cursor-api-key";
+export function cursorCredentialMissingReason() {
+    return "Cursor API key is missing from the credential root. Configure credentials via `sf providers` / the operator console Providers page, then retry.";
+}
+/** Publish the credential-root Cursor key onto the process for a cursor/* model. */
+export function bindCursorApiKey(modelId) {
+    if (!isCursorModelRef(modelId))
+        return undefined;
+    const key = readCursorApiKey();
+    if (!key) {
+        throw new Error(cursorCredentialMissingReason());
+    }
+    if (process.env.CURSOR_API_KEY?.trim())
+        return undefined;
+    process.env.CURSOR_API_KEY = key;
+    return () => {
+        delete process.env.CURSOR_API_KEY;
+    };
+}
 export function readCursorApiKey(env = process.env) {
     let fromEnv;
     try {
@@ -153,7 +170,7 @@ export function readCursorApiKey(env = process.env) {
     if (fromEnv !== undefined && fromEnv.trim() !== "") {
         return fromEnv.trim();
     }
-    const filePath = path.join(globalStageflowHome(), "agent", CURSOR_API_KEY_FILE_NAME);
+    const filePath = path.join(globalCredentialRoot(), "agent", CURSOR_API_KEY_FILE_NAME);
     if (!existsSync(filePath)) {
         return undefined;
     }

package/dist/agent/fakeAgent.d.ts

@@ -1,5 +1,5 @@
 import type { StageRoots } from "../runtime/stageRoots.js";
-import type { AgentPort, OpaqueAnswer, OpaqueWaitRequest, StageHandle, StageRunInput, StageRunResult } from "./port.js";
+import type { StagePort, OpaqueAnswer, OpaqueWaitRequest, StageHandle, StageRunInput, StageRunResult } from "./port.js";
 export type FakeAgentBehavior = {
     type: "emit";
     envelope: unknown;
@@ -17,7 +17,7 @@ export type FakeAgentBehavior = {
 };
 export type RecordedStageRoots = StageRoots;
 export declare function fakeHitlResumePath(roots: Pick<StageRoots, "runWorkspaceDir">, stageId: string): string;
-export declare class FakeAgent implements AgentPort {
+export declare class FakeAgent implements StagePort {
     private readonly behavior;
     lastRoots?: RecordedStageRoots;
     receivedAnswers: OpaqueAnswer[];
@@ -25,6 +25,6 @@ export declare class FakeAgent implements AgentPort {
     openStage(input: StageRunInput): StageHandle;
     runStage(input: StageRunInput): Promise<StageRunResult>;
 }
-export declare function scriptedFakeAgent(behaviors: FakeAgentBehavior[]): AgentPort & {
+export declare function scriptedFakeAgent(behaviors: FakeAgentBehavior[]): StagePort & {
     recorded: RecordedStageRoots[];
 };

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

@@ -3,7 +3,7 @@ import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
 import { type StageActivityObserver } from "./activityObserver.js";
-import type { AgentPort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
+import type { StagePort, OpaqueAnswer, StageHandle, StageHandleCloseOptions, StageRunInput, StageRunResult } from "./port.js";
 import type { StageGateKind } from "../types/stage.js";
 import { type StageUsage } from "../types/usage.js";
 import { STAGEFLOW_PATH_DENIED } from "../runstore/workspaceLayout.js";
@@ -133,7 +133,7 @@ export type ReconstructedStageSession = {
  * Does not auto-continue the model turn — U4 owns the yield loop.
  */
 export declare function reconstructStageSessionForAnswer(input: StageRunInput, answer: OpaqueAnswer): Promise<ReconstructedStageSession>;
-export declare class PiAgentAdapter implements AgentPort {
+export declare class PiAgentAdapter implements StagePort {
     openStage(input: StageRunInput): StageHandle;
     runStage(input: StageRunInput): Promise<StageRunResult>;
 }