stageflow 0.33.0 → 0.35.0

package/dist/agent/piAdapter.js

@@ -1,5 +1,5 @@
 /**
- * Pi implementation of AgentPort.
+ * Pi implementation of StagePort.
  *
  * One stage = one `createAgentSession` (single-shot SDK path, not
  * AgentSessionRuntime / interactive / RPC). The session is sealed from host
@@ -35,19 +35,24 @@ import path from "node:path";
 import { BROWSER_SKILL_NAME } from "../config/builtinSkills.js";
 import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError } from "../config/resolveStageMcpServers.js";
-import { attachIsolatedMcp, STAGEFLOW_PI_MCP_EXTENSION_NAME, } from "./piIsolatedMcp.js";
+import { attachIsolatedMcp, STAGEFLOW_PI_MCP_EXTENSION_NAME, UNREQUESTED_MCP_ADAPTER_TOOLS, } from "./piIsolatedMcp.js";
+import { warmIsolatedMcpMetadata } from "./piIsolatedMcpProbe.js";
+import { createToolOutputBudgetExtension, STAGEFLOW_TOOL_OUTPUT_EXTENSION_NAME, } from "./toolOutputBudgetExtension.js";
+import { TOOL_OUTPUT_ARTIFACT_DIR } from "./toolOutputSpill.js";
 import { createPiAgentSession, createSealedResourceLoader, } from "./piSessionFactory.js";
 import { isAdvancingEnvelope } from "../envelope/check.js";
 import { formatFeedbackLoopContext } from "../prompt/feedbackLoopContext.js";
 import { formatPriorEnvelope } from "../prompt/priorEnvelope.js";
 import { attemptContext, noAttemptContext, } from "../runtime/stageAttemptContext.js";
 import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
+import { remindUntilEmitted } from "./stageTurnDriver.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 { isCursorModelRef, readCursorApiKey } from "./cursorProvider.js";
 import { findProviderSupport } from "./providerSupport.js";
 import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
 import { createStageActivityObserver, } from "./activityObserver.js";
@@ -55,6 +60,8 @@ import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./por
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
 import { globalStageflowHome } from "../project/globalHome.js";
+import { isUsableAuthFile, STAGEFLOW_AGENT_AUTH_PATH_ENV, } from "../runtime/credentialBinding.js";
+import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 import { durableRootFileToolDenial, STAGEFLOW_PATH_DENIED, } from "../runstore/workspaceLayout.js";
 export { STAGEFLOW_PATH_DENIED };
 export { createSealedResourceLoader } from "./piSessionFactory.js";
@@ -462,6 +469,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
     ].filter((dir) => dir !== undefined);
     const skillBaseDir = skillBaseDirs.length > 0 ? skillBaseDirs.join(", ") : undefined;
     const browserGuidance = formatBrowserGuidance(input);
+    const toolOutputGuidance = Object.keys(input.resolvedMcpServers ?? {}).length > 0 ||
+        (input.stage.email?.length ?? 0) > 0
+        ? `Large tool results are saved automatically as stage artifacts under ${attemptArtifactsPath}${TOOL_OUTPUT_ARTIFACT_DIR}/. The tool result names the path. Read or grep that file; do not copy tool output into ${artifactToolName ?? "an artifact"}.`
+        : "";
     const artifactGuidance = input.roots.mode === "bound" && artifactToolName !== undefined
         ? [
             `Project checkout (agent cwd): ${input.roots.checkoutRoot}`,
@@ -499,6 +510,7 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             : "",
         "",
         artifactGuidance,
+        toolOutputGuidance,
         browserGuidance,
         emitHint,
     ]
@@ -543,15 +555,26 @@ export function composeFeedbackResumePrompt(input) {
         formatFeedbackLoopContext(input.feedbackLoopContext, input.sessionMode ?? "feedback_resume"),
     ].join("\n\n");
 }
-function collectMcpExtensionToolNames(loader) {
+function mcpExtensionTools(loader) {
     const inlinePath = `<inline:${STAGEFLOW_PI_MCP_EXTENSION_NAME}>`;
+    return loader
+        .getExtensions()
+        .extensions.filter((ext) => ext.path === inlinePath)
+        .flatMap((ext) => [...ext.tools.keys()]);
+}
+function mcpToolMetadataMissing(loader) {
+    return mcpExtensionTools(loader).includes("mcp");
+}
+function collectMcpExtensionToolNames(loader) {
     const names = [];
-    for (const ext of loader.getExtensions().extensions) {
-        if (ext.path !== inlinePath)
-            continue;
-        names.push(...ext.tools.keys());
-    }
-    return names;
+    const unrequested = [];
+    for (const name of mcpExtensionTools(loader)) {
+        if (UNREQUESTED_MCP_ADAPTER_TOOLS.has(name))
+            unrequested.push(name);
+        else
+            names.push(name);
+    }
+    return unrequested.length > 0 ? { ok: false, unrequested } : { ok: true, names };
 }
 async function shutdownSession(session) {
     if (!session) {
@@ -574,7 +597,10 @@ async function shutdownSession(session) {
         // ignore dispose errors during teardown
     }
 }
-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 };
     }
@@ -800,6 +826,26 @@ export function injectOpaqueAnswerIntoSession(sessionManager, answer) {
 async function prepareStageSessionWiring(input, sessionManager, existingAskWaitChannel) {
     const { roots } = input;
     const provider = findProviderSupport(input.stage.model);
+    if (process.env[SF_STAGE_WORKER] === "1" && !provider) {
+        if (!roots.authPath || !isUsableAuthFile(roots.authPath)) {
+            const authPath = roots.authPath;
+            return {
+                ok: false,
+                reason: authPath
+                    ? `Stage provider auth is not configured (auth file missing or empty: ${authPath}).`
+                    : `Stage provider auth is not configured (${STAGEFLOW_AGENT_AUTH_PATH_ENV} is unset).`,
+            };
+        }
+    }
+    if (process.env[SF_STAGE_WORKER] === "1" &&
+        provider &&
+        isCursorModelRef(input.stage.model) &&
+        !readCursorApiKey()) {
+        return {
+            ok: false,
+            reason: "Stage provider auth is not configured (Cursor API key missing from the credential root).",
+        };
+    }
     const capture = {};
     const usage = emptyStageUsage();
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
@@ -859,7 +905,9 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         const settingsManager = SettingsManager.inMemory({
             compaction: { enabled: false },
         });
-        attached = await attachIsolatedMcp(input.resolvedMcpServers);
+        attached = await attachIsolatedMcp(input.resolvedMcpServers, {
+            lifecycle: "eager",
+        });
         const failAfterAttach = (reason) => {
             attached?.cancel?.();
             restoreProvider?.();
@@ -876,6 +924,21 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                         : {}),
                 }),
             },
+            {
+                name: STAGEFLOW_TOOL_OUTPUT_EXTENSION_NAME,
+                factory: createToolOutputBudgetExtension({
+                    runWorkspaceDir: roots.runWorkspaceDir,
+                    stageId: runtimeStageId(input),
+                    attempt: roots.attempt ?? 1,
+                    exempt: new Set([
+                        "read",
+                        "bash",
+                        emitDef.name,
+                        artifactDef.name,
+                        askDef?.name ?? "ask_operator",
+                    ]),
+                }),
+            },
             ...(attached.extensionFactories ?? []),
         ];
         const loader = createSealedResourceLoader({
@@ -889,6 +952,23 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             ...(attached.eventBus !== undefined ? { eventBus: attached.eventBus } : {}),
         });
         await loader.reload();
+        if (attached.extensionFactories !== undefined &&
+            input.resolvedMcpServers !== undefined &&
+            mcpToolMetadataMissing(loader)) {
+            // A cold adapter metadata cache registers only the `mcp` gateway at load,
+            // and the session allowlist is fixed at load. Warm the cache, then reload
+            // so the declared servers' direct tools exist when the allowlist is built.
+            try {
+                await warmIsolatedMcpMetadata(input.resolvedMcpServers, { cwd: roots.cwd });
+            }
+            catch (err) {
+                return failAfterAttach(err instanceof Error ? err.message : String(err));
+            }
+            await loader.reload();
+            if (mcpToolMetadataMissing(loader)) {
+                return failAfterAttach(`MCP tool metadata unavailable for: ${Object.keys(input.resolvedMcpServers).join(", ")}`);
+            }
+        }
         const extensionErrors = loader.getExtensions().errors;
         if (extensionErrors.length > 0) {
             return failAfterAttach(`Failed to load Pi extension(s): ${extensionErrors
@@ -912,7 +992,11 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             : [emitTool, artifactTool];
         const tools = resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? "ask_operator", gateKinds);
         if (attached.extensionFactories !== undefined) {
-            tools.push(...collectMcpExtensionToolNames(loader));
+            const mcpTools = collectMcpExtensionToolNames(loader);
+            if (!mcpTools.ok) {
+                return failAfterAttach(`MCP adapter registered unrequested tool(s): ${mcpTools.unrequested.join(", ")}`);
+            }
+            tools.push(...mcpTools.names);
         }
         if (input.email) {
             const permitted = new Set(input.stage.email?.flatMap(permission => permission.operations));
@@ -1178,6 +1262,7 @@ export class PiAgentAdapter {
         let wiring;
         let unsubscribeProgress;
         let prepareError;
+        let closing = false;
         const preparePromise = (async () => {
             if (forceNewSession) {
                 await mkdir(path.dirname(sessionFile), { recursive: true });
@@ -1213,15 +1298,30 @@ export class PiAgentAdapter {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
-                const workPromise = work();
+                const live = session;
+                const capture = wiring.capture;
+                const emitToolName = wiring.emitDefName;
+                const turns = {
+                    prompt: (text) => live.prompt(text),
+                    get messages() {
+                        return live.messages ?? live.agent?.state?.messages ?? [];
+                    },
+                };
+                const workPromise = (async () => {
+                    await work();
+                    return remindUntilEmitted(turns, capture, {
+                        emitToolName,
+                        shouldStop: () => closing || controller.signal.aborted,
+                    });
+                })();
                 const abortPromise = new Promise((_, reject) => {
                     controller.signal.addEventListener("abort", () => {
                         void session?.abort();
                         reject(new Error(stageTimeoutReason(timeoutMs)));
                     });
                 });
-                await Promise.race([workPromise, abortPromise]);
-                return { ...resultFromCapture(wiring.capture), usage: wiring.usage };
+                const outcome = await Promise.race([workPromise, abortPromise]);
+                return { ...resultFromCapture(capture, outcome.providerError), usage: wiring.usage };
             }
             catch (err) {
                 if (sessionManager) {
@@ -1292,6 +1392,7 @@ export class PiAgentAdapter {
                 }
                 : undefined,
             onClose: async (closeOptions) => {
+                closing = true;
                 await preparePromise.catch(() => undefined);
                 if (closeOptions?.park) {
                     if (sessionManager) {

package/dist/agent/piIsolatedMcp.d.ts

@@ -17,6 +17,7 @@ export type IsolatedMcpAttach = {
     connecting: Promise<void> | undefined;
     cancel?: () => void;
 };
+export declare const UNREQUESTED_MCP_ADAPTER_TOOLS: ReadonlySet<string>;
 export declare function emitIsolatedMcpStatus(eventBus: EventBus, servers: ReadonlyArray<{
     name: string;
     status: string;

package/dist/agent/piIsolatedMcp.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { createEventBus, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError, } from "../config/resolveStageMcpServers.js";
 import { globalStageflowHome } from "../project/globalHome.js";
+import { TOOL_OUTPUT_HARD_CEILING_BYTES } from "./toolOutputBudget.js";
 export const STAGEFLOW_PI_MCP_EXTENSION_NAME = "stageflow-mcp";
 const MCP_STATUS_EVENT = "pi-mcp-adapter/status/v1";
 const DEFAULT_ISOLATED_MCP_CONNECT_TIMEOUT_MS = 30_000;
@@ -13,11 +14,25 @@ export function jitiFsCacheDir() {
 export function resetCreateMcpAdapterCacheForTests() {
     cachedCreateMcpAdapter = undefined;
 }
+// Stages get only the declared servers' direct tools: no mcpScript sandbox and
+// no `mcp` gateway. The adapter's output guard is a backstop; the stage budget
+// lives in toolOutputBudgetExtension.
 const ISOLATED_MCP_SETTINGS = {
     directTools: true,
     elicitation: false,
     hostConfigDiscovery: "off",
+    scriptMode: false,
+    disableProxyTool: true,
+    outputGuard: {
+        maxBytes: TOOL_OUTPUT_HARD_CEILING_BYTES,
+        maxLines: Number.MAX_SAFE_INTEGER,
+        detailsMaxBytes: 16 * 1024,
+    },
 };
+export const UNREQUESTED_MCP_ADAPTER_TOOLS = new Set([
+    "mcpScript",
+    "mcp",
+]);
 const SUCCESS_STATUSES = new Set([
     "connected",
     "cached",
@@ -48,7 +63,10 @@ function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
     }
     return {
         mcpServers,
-        settings: { ...ISOLATED_MCP_SETTINGS },
+        settings: {
+            ...ISOLATED_MCP_SETTINGS,
+            outputGuard: { ...ISOLATED_MCP_SETTINGS.outputGuard },
+        },
     };
 }
 async function loadCreateMcpAdapter() {

package/dist/agent/piIsolatedMcpProbe.d.ts

@@ -1,3 +1,4 @@
+import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 export declare const PROJECT_MCP_PROBE_TIMEOUT_MS = 30000;
 export type ProjectMcpProbeStatus = "connected" | "needs_auth" | "connect_failed" | "unresolved_var" | "invalid_config" | "missing_catalog" | "cancelled";
 export type ProjectMcpProbeResult = {
@@ -13,3 +14,13 @@ export type ProbeProjectMcpServerOptions = {
     timeoutMs?: number;
 };
 export declare function probeProjectMcpServer(options: ProbeProjectMcpServerOptions): Promise<ProjectMcpProbeResult>;
+/**
+ * Connects the snapshot's servers headlessly so the adapter writes its tool
+ * metadata cache into the current Pi agent dir. A sealed loader reloaded after
+ * this registers the servers' direct tools at load time, which is when the
+ * stage tool allowlist is computed.
+ */
+export declare function warmIsolatedMcpMetadata(snapshot: ResolvedMcpServers, options: {
+    cwd: string;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/agent/piIsolatedMcpProbe.js

@@ -290,3 +290,23 @@ export async function probeProjectMcpServer(options) {
         await dispose();
     }
 }
+/**
+ * Connects the snapshot's servers headlessly so the adapter writes its tool
+ * metadata cache into the current Pi agent dir. A sealed loader reloaded after
+ * this registers the servers' direct tools at load time, which is when the
+ * stage tool allowlist is computed.
+ */
+export async function warmIsolatedMcpMetadata(snapshot, options) {
+    const attached = await piIsolatedMcp.attachIsolatedMcp(snapshot, {
+        lifecycle: "eager",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    });
+    const shutdown = instantiateProbeFactories(attached, options.cwd);
+    try {
+        await attached.connecting;
+    }
+    finally {
+        attached.cancel?.();
+        await shutdown();
+    }
+}

package/dist/agent/port.d.ts

@@ -122,12 +122,12 @@ export interface StageHandle {
     deliverAnswer(answer: OpaqueAnswer): void;
     close(options?: StageHandleCloseOptions): Promise<void>;
 }
-export interface AgentPort {
+export interface StagePort {
     openStage(input: StageRunInput): StageHandle;
     runStage(input: StageRunInput): Promise<StageRunResult>;
 }
 /** Thin non-HITL wrapper: open → next; unexpected wait fails closed. */
-export declare function runStageViaOpen(port: Pick<AgentPort, "openStage">, input: StageRunInput): Promise<StageRunResult>;
+export declare function runStageViaOpen(port: Pick<StagePort, "openStage">, input: StageRunInput): Promise<StageRunResult>;
 /** Wrap a single-shot runner as a handle that never waits (Pi U2 shim). */
 export declare function createCompletedOnlyStageHandle(options: {
     stageId: string;

package/dist/agent/providerAuth.js

@@ -1,6 +1,8 @@
+import { existsSync } from "node:fs";
 import { mkdir, writeFile, chmod, access } from "node:fs/promises";
 import path from "node:path";
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { parseCredentialSource, resolveCredentialBinding, writeCredentialSourceToContext, isUsableAuthFile, } from "../runtime/credentialBinding.js";
 import { getCursorHostStatus } from "./cursorProvider.js";
 import { readPersistedCredentialSourceFromContext, } from "../runtime/settingsFile.js";
@@ -23,7 +25,13 @@ export class ProviderAuthError extends Error {
         this.status = status;
     }
 }
-const defaultCreateRuntime = async (authPath) => ModelRuntime.create({ authPath, refreshOnCreate: false });
+const defaultCreateRuntime = async (authPath) => ModelRuntime.create({
+    authPath,
+    // ModelRuntime otherwise reads models.json from PI_CODING_AGENT_DIR,
+    // which stays on the process data directory.
+    modelsPath: path.join(path.dirname(authPath), "models.json"),
+    refreshOnCreate: false,
+});
 async function ensurePiAuthFile(authPath) {
     const resolved = path.resolve(authPath);
     await mkdir(path.dirname(resolved), { recursive: true });
@@ -49,6 +57,31 @@ export async function openRuntime(cwd, ctx = defaultContext) {
     const binding = resolveCredentialBinding(cwd);
     return ctx.createRuntime(binding.authPath);
 }
+function catalogRuntime() {
+    const providers = builtinProviders();
+    return {
+        getProviders: () => providers,
+        getProvider: (id) => providers.find((provider) => provider.id === id),
+        getProviderAuthStatus: () => ({ configured: false }),
+        listCredentials: async () => [],
+        checkAuth: async () => undefined,
+        login: async () => {
+            throw new ProviderAuthError("Provider login failed", 500);
+        },
+        logout: async () => {
+            throw new ProviderAuthError("Provider logout failed", 500);
+        },
+    };
+}
+async function openReadRuntime(cwd, ctx) {
+    const binding = resolveCredentialBinding(cwd);
+    // ModelRuntime.create writes auth.json when that file is missing.
+    if (ctx.createRuntime === defaultCreateRuntime &&
+        !existsSync(binding.authPath)) {
+        return catalogRuntime();
+    }
+    return ctx.createRuntime(binding.authPath);
+}
 export function isLoginCapable(provider) {
     return (provider.auth?.oauth != null || provider.auth?.apiKey?.login != null);
 }
@@ -133,7 +166,7 @@ export async function statusForProvider(runtime, providerId) {
     return mapped;
 }
 export async function listProviders(cwd, ctx = defaultContext) {
-    const runtime = await openRuntime(cwd, ctx);
+    const runtime = await openReadRuntime(cwd, ctx);
     return {
         authShell: "pi",
         via: "pi",
@@ -144,7 +177,7 @@ export async function listProviders(cwd, ctx = defaultContext) {
     };
 }
 export async function getAuthStatus(cwd, providerId, ctx = defaultContext) {
-    const runtime = await openRuntime(cwd, ctx);
+    const runtime = await openReadRuntime(cwd, ctx);
     if (providerId !== undefined) {
         if (!runtime.getProvider(providerId)) {
             throw new ProviderAuthError("Provider not found", 404);

package/dist/agent/{resolveAgentPort.d.ts → resolveStagePort.d.ts}

@@ -1,5 +1,5 @@
 import { type AgentBackendId } from "./agentBackend.js";
-import type { AgentPort } from "./port.js";
+import type { StagePort } from "./port.js";
 import type { LoadedManifest } from "../types/stageflowManifest.js";
 export type AgentSelection = {
     /** stageflow.yaml top-level `agent`. */
@@ -10,14 +10,14 @@ export type AgentSelection = {
     stage?: AgentBackendId;
 };
 /** 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;
+export declare function resolveStageBackend(selection?: AgentSelection): AgentBackendId;
+/** Existing Pi StagePort. Hosted runs pass this into createHostedRuntime. */
+export declare function createPiStagePort(): StagePort;
+export declare function resolveStagePort(selection?: AgentSelection): StagePort;
 /** 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;
+export declare function globalStageBackendFromManifest(manifest: LoadedManifest | null): AgentBackendId | undefined;
 /**
- * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * Resolves an StagePort using only the global (stageflow.yaml) tier — for
  * the three call sites that construct an agent before any pipeline is
  * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
  * Named explicitly so it's clear these sites are scoped to the global tier
@@ -25,4 +25,4 @@ export declare function globalAgentBackendFromManifest(manifest: LoadedManifest
  * through `stageWorker.ts`, which resolves the full stage > pipeline >
  * global chain once it has loaded the specific pipeline and stage.
  */
-export declare function resolveGlobalOnlyAgentPort(projectRoot: string): Promise<AgentPort>;
+export declare function resolveGlobalOnlyStagePort(projectRoot: string): Promise<StagePort>;

package/dist/agent/{resolveAgentPort.js → resolveStagePort.js}

@@ -3,31 +3,31 @@ import { PiAgentAdapter } from "./piAdapter.js";
 import { ClaudeAgentAdapter } from "./claudeAdapter.js";
 import { loadStageflowManifestOutcome } from "../config/loadStageflowManifest.js";
 /** stage > pipeline > global > "pi", with stage gated off for now. */
-export function resolveAgentBackend(selection = {}) {
+export function resolveStageBackend(selection = {}) {
     if (STAGE_LEVEL_AGENT_OVERRIDE_ENABLED && selection.stage !== undefined) {
         return selection.stage;
     }
     return selection.pipeline ?? selection.global ?? "pi";
 }
-/** Existing Pi AgentPort. Hosted runs pass this into createHostedRuntime. */
-export function createPiAgentPort() {
+/** Existing Pi StagePort. Hosted runs pass this into createHostedRuntime. */
+export function createPiStagePort() {
     return new PiAgentAdapter();
 }
-export function resolveAgentPort(selection = {}) {
-    const backend = resolveAgentBackend(selection);
+export function resolveStagePort(selection = {}) {
+    const backend = resolveStageBackend(selection);
     switch (backend) {
         case "pi":
-            return createPiAgentPort();
+            return createPiStagePort();
         case "claude":
             return new ClaudeAgentAdapter();
     }
 }
 /** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
-export function globalAgentBackendFromManifest(manifest) {
+export function globalStageBackendFromManifest(manifest) {
     return manifest ? asAgentBackendId(manifest.manifest.agent) : undefined;
 }
 /**
- * Resolves an AgentPort using only the global (stageflow.yaml) tier — for
+ * Resolves an StagePort using only the global (stageflow.yaml) tier — for
  * the three call sites that construct an agent before any pipeline is
  * known (`cli.ts`'s ui/mcp servers, `runCommand.ts`, `runsCommand.ts`).
  * Named explicitly so it's clear these sites are scoped to the global tier
@@ -35,9 +35,9 @@ export function globalAgentBackendFromManifest(manifest) {
  * through `stageWorker.ts`, which resolves the full stage > pipeline >
  * global chain once it has loaded the specific pipeline and stage.
  */
-export async function resolveGlobalOnlyAgentPort(projectRoot) {
+export async function resolveGlobalOnlyStagePort(projectRoot) {
     const outcome = await loadStageflowManifestOutcome(projectRoot);
-    return resolveAgentPort({
-        global: outcome.ok ? globalAgentBackendFromManifest(outcome.value) : undefined,
+    return resolveStagePort({
+        global: outcome.ok ? globalStageBackendFromManifest(outcome.value) : undefined,
     });
 }

package/dist/agent/stageTurnDriver.d.ts

@@ -0,0 +1,33 @@
+import type { EmitCapture } from "../tools/emitStageEnvelope.js";
+/** Follow-up turns sent when the agent ends its turn without an accepted envelope. */
+export declare const DEFAULT_EMIT_REMINDERS = 2;
+/** The slice of a Pi session the driver needs; a fake in tests. */
+export type StageTurnSession = {
+    prompt(text: string): Promise<void>;
+    readonly messages: readonly unknown[];
+};
+export type RemindOptions = {
+    emitToolName: string;
+    maxReminders?: number;
+    /** True once the stage is closing, parked, or timed out: never start another turn then. */
+    shouldStop: () => boolean;
+};
+export type RemindOutcome = {
+    reminders: number;
+    /** Set when the last turn ended on a provider error; no reminder is sent after one. */
+    providerError?: string;
+};
+/** Trimmed, length-capped provider error text for a stage failure reason. */
+export declare function formatProviderError(text: string | undefined): string;
+/**
+ * Error text of the last assistant turn when it ended on a provider error (bad key, auth,
+ * model unavailable, or a transient error Pi already gave up retrying). Undefined otherwise.
+ */
+export declare function lastTurnProviderError(messages: readonly unknown[]): string | undefined;
+export declare function emitReminderPrompt(emitToolName: string, attempt: number, max: number, rejectedEmit?: string): string;
+/**
+ * Called after a turn returns. While no envelope was accepted, nudge the agent with a short
+ * follow-up turn, up to `maxReminders` times. Stops at once when an envelope is captured,
+ * the stage is stopping, the turn was aborted, or the turn ended on a provider error.
+ */
+export declare function remindUntilEmitted(session: StageTurnSession, capture: EmitCapture, options: RemindOptions): Promise<RemindOutcome>;

package/dist/agent/stageTurnDriver.js

@@ -0,0 +1,64 @@
+/** Follow-up turns sent when the agent ends its turn without an accepted envelope. */
+export const DEFAULT_EMIT_REMINDERS = 2;
+const PROVIDER_ERROR_MAX_CHARS = 500;
+function lastAssistant(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m && typeof m === "object" && m.role === "assistant")
+            return m;
+    }
+    return undefined;
+}
+/** Trimmed, length-capped provider error text for a stage failure reason. */
+export function formatProviderError(text) {
+    const t = text?.trim() ? text.trim() : "the model provider returned an error";
+    return t.length > PROVIDER_ERROR_MAX_CHARS ? `${t.slice(0, PROVIDER_ERROR_MAX_CHARS)}…` : t;
+}
+/**
+ * Error text of the last assistant turn when it ended on a provider error (bad key, auth,
+ * model unavailable, or a transient error Pi already gave up retrying). Undefined otherwise.
+ */
+export function lastTurnProviderError(messages) {
+    const m = lastAssistant(messages);
+    if (!m || m.stopReason !== "error")
+        return undefined;
+    return formatProviderError(typeof m.errorMessage === "string" ? m.errorMessage : undefined);
+}
+function lastTurnAborted(messages) {
+    return lastAssistant(messages)?.stopReason === "aborted";
+}
+export function emitReminderPrompt(emitToolName, attempt, max, rejectedEmit) {
+    const lines = [
+        `Reminder ${attempt} of ${max}: your turn ended without an accepted ${emitToolName} call, so this stage has not finished.`,
+    ];
+    if (rejectedEmit !== undefined) {
+        lines.push(`Your last ${emitToolName} call was rejected: ${rejectedEmit}`);
+        lines.push(`Fix that and call ${emitToolName} again.`);
+    }
+    else {
+        lines.push(`Continue the stage's work if any is left, then call ${emitToolName}.`);
+    }
+    lines.push(`If the stage cannot be completed, call ${emitToolName} with status "failure" and a summary that says why. Do not end your turn without calling it.`);
+    return lines.join("\n");
+}
+/**
+ * Called after a turn returns. While no envelope was accepted, nudge the agent with a short
+ * follow-up turn, up to `maxReminders` times. Stops at once when an envelope is captured,
+ * the stage is stopping, the turn was aborted, or the turn ended on a provider error.
+ */
+export async function remindUntilEmitted(session, capture, options) {
+    const max = options.maxReminders ?? DEFAULT_EMIT_REMINDERS;
+    let reminders = 0;
+    for (;;) {
+        if (capture.envelope)
+            return { reminders };
+        const providerError = lastTurnProviderError(session.messages);
+        if (providerError !== undefined)
+            return { reminders, providerError };
+        if (options.shouldStop() || lastTurnAborted(session.messages) || reminders >= max) {
+            return { reminders };
+        }
+        reminders++;
+        await session.prompt(emitReminderPrompt(options.emitToolName, reminders, max, capture.error));
+    }
+}