stageflow 0.42.0 → 0.46.0

package/dist/agent/piAdapter.js

@@ -33,7 +33,7 @@ import { existsSync } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 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 { defineTool, ModelRuntime, resolveCliModel, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { StageMcpError } from "../config/resolveStageMcpServers.js";
 import { attachIsolatedMcp, STAGEFLOW_PI_MCP_EXTENSION_NAME, UNREQUESTED_MCP_ADAPTER_TOOLS, } from "./piIsolatedMcp.js";
 import { warmIsolatedMcpMetadata } from "./piIsolatedMcpProbe.js";
@@ -61,6 +61,7 @@ import { findProviderSupport } from "./providerSupport.js";
 import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
 import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runtimeStageId, runStageViaOpen } from "./port.js";
+import { addCompactionUsage, compactionActivityEvent, } from "./compactionEvents.js";
 import { addModelUsage, emptyStageUsage } from "../types/usage.js";
 import { TIMEOUT_ABORT_TOOL_RESULT, composeTimeoutResumePrompt, stageTimeoutReason, } from "./stageTimeout.js";
 import { globalStageflowHome } from "../project/globalHome.js";
@@ -68,6 +69,10 @@ import { isUsableAuthFile, STAGEFLOW_AGENT_AUTH_PATH_ENV, } from "../runtime/cre
 import { SF_STAGE_WORKER } from "../runtime/stageWorkerProtocol.js";
 import { durableRootFileToolDenial, STAGEFLOW_PATH_DENIED, } from "../runstore/workspaceLayout.js";
 export { STAGEFLOW_PATH_DENIED };
+import { createPiSettingsManager } from "./piSettings.js";
+import { createSessionContextWiring } from "../compaction/sessionWiring.js";
+import { ASK_OPERATOR_TOOL_NAME } from "../tools/stageToolNames.js";
+import { WORKING_STATE_GUIDANCE } from "../compaction/workingState.js";
 export { createSealedResourceLoader } from "./piSessionFactory.js";
 export const STAGEFLOW_PATH_DENY_EXTENSION_NAME = "stageflow-path-deny";
 const PATH_DENY_FILE_TOOLS = new Set(["read", "write", "edit"]);
@@ -102,7 +107,7 @@ export function createDurableRootPathDenyExtension(options) {
  * `write_stage_artifact` when registered (always, for bound and unbound —
  * bound/unbound only gates cwd / env bind).
  */
-export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = "ask_operator", gateKinds) {
+export function resolveStageToolNames(emitToolName, artifactToolName, askOperatorToolName = ASK_OPERATOR_TOOL_NAME, gateKinds) {
     const tools = [
         "read",
         "bash",
@@ -425,11 +430,37 @@ function attachStageProgress(session, onActivity, usage, onAssistantTextDelta) {
         writeStderr: true,
     });
     const verbose = readActivityVerbose();
+    let lastContextPercent = -1;
     const unsubscribe = session.subscribe((event) => {
-        routeSessionEventToProgress(event, {
-            observer,
-            verbose,
-            usage,
+        const raw = event;
+        routeSessionEventToProgress(raw, { observer, verbose, usage });
+        if (raw.type === "compaction_end") {
+            lastContextPercent = -1;
+            const end = raw;
+            if (usage)
+                addCompactionUsage(usage, session.model?.id, end);
+            observer.onActivity(compactionActivityEvent(end, session.getContextUsage()?.tokens ?? null));
+            const after = end.result?.estimatedTokensAfter;
+            const window = session.getContextUsage()?.contextWindow ?? 0;
+            if (session.getContextUsage()?.tokens == null && typeof after === "number" && Number.isFinite(after) && window > 0) {
+                lastContextPercent = Math.min(100, Math.round((after / window) * 100));
+                observer.onActivity({ event: "context_usage", tokens: after, contextWindow: window, percent: lastContextPercent });
+            }
+        }
+        if (raw.type !== "message_end" && raw.type !== "compaction_end")
+            return;
+        const context = session.getContextUsage();
+        if (context?.tokens == null || context.contextWindow <= 0)
+            return;
+        const percent = Math.min(100, Math.round((context.tokens / context.contextWindow) * 100));
+        if (percent === lastContextPercent)
+            return;
+        lastContextPercent = percent;
+        observer.onActivity({
+            event: "context_usage",
+            tokens: context.tokens,
+            contextWindow: context.contextWindow,
+            percent,
         });
     });
     return () => {
@@ -437,6 +468,20 @@ function attachStageProgress(session, onActivity, usage, onAssistantTextDelta) {
         observer.dispose();
     };
 }
+function formatGrantedArtifacts(grants) {
+    if (grants === undefined || grants.length === 0) {
+        return "No prior artifacts are granted in this sandbox. Do not open stages/<id>/attempts/... host layouts.";
+    }
+    const lines = [
+        "Prior artifacts are read-only. Read the sandbox path on each line. A file grant is a file at that path. A directory grant is a directory. Do not open stages/<id>/attempts/... host layouts.",
+    ];
+    for (const grant of grants) {
+        const name = grant.listedPath.split("/").pop() || grant.listedPath;
+        lines.push(`- ${name} (${grant.kind}) → ${grant.containerPath}`);
+        lines.push(`  from ${grant.listedPath}`);
+    }
+    return lines.join("\n");
+}
 function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName) {
     let emitHint = emitHintOverride ??
         `Required final action: call ${emitToolName} exactly once with status, summary, and artifacts (run-relative paths).`;
@@ -480,14 +525,18 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         : "";
     const artifactGuidance = sandboxed
         ? [
-            "Sandbox desk: /workspace. read, bash, write, and edit run only inside that desk.",
+            "Sandbox desk: /workspace. read, write, and edit run only inside that desk.",
+            input.roots.readonlyDir
+                ? `One folder is mounted read-only at ${input.roots.readonlyDir}. Read the files there. If a file you were given is not in that folder, stop and say so. Do not create stand-in documents.`
+                : "The host filesystem is not mounted.",
             input.roots.checkoutRoot
                 ? `Checkout: /workspace/checkout. The host checkout path is not mounted.`
                 : "This stage has no checkout. Scratch files go in /workspace/work.",
-            "Attempt artifacts are at /workspace/artifacts. Scratch space is /workspace/work.",
+            "Scratch space is /workspace/work. Desk /workspace/artifacts is not durable — bash or builtin writes there do not persist for emit or the next stage.",
             artifactToolName !== undefined
-                ? `Create factory stage artifacts only with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`
-                : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`,
+                ? `Durable stage artifacts only via ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`
+                : `Durable stage artifacts belong under ${attemptArtifactsPath} relative to the run folder.`,
+            formatGrantedArtifacts(input.roots.artifactGrants),
         ].join("\n")
         : input.roots.mode === "bound" && artifactToolName !== undefined
             ? [
@@ -569,6 +618,30 @@ export function composeStageUserPrompt(input, emitToolName, emitHintOverride, ar
     }
     return body;
 }
+/**
+ * Pi stages carry the whole assignment (task, prior envelopes, envelope
+ * contract, guidance) in the system prompt: compaction never summarizes it.
+ */
+export function composeStagePiSystemPrompt(input, emitToolName, emitHintOverride, artifactToolName) {
+    return [
+        input.stage.system_prompt,
+        "",
+        "# Working state",
+        WORKING_STATE_GUIDANCE,
+        "",
+        "# Stage assignment",
+        buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName),
+    ].join("\n");
+}
+export function composeStagePiKickoffPrompt(input) {
+    const body = "Begin this stage. Your task, inputs, constraints and the required final action are in your system prompt under \"Stage assignment\".";
+    if (input.stage.skill !== undefined)
+        return `/skill:${input.stage.skill} ${body}`;
+    if (input.browserSkillFilePath !== undefined && input.stage.browser !== undefined) {
+        return `/skill:${BROWSER_SKILL_NAME} ${body}`;
+    }
+    return body;
+}
 export function composeFeedbackResumePrompt(input) {
     if (input.feedbackLoopContext === undefined) {
         throw new Error("feedback_resume requires feedbackLoopContext");
@@ -744,7 +817,7 @@ export async function repairPrematureAskOperatorClosure(sessionFile) {
         const message = entry.message;
         if (!message || message.role !== "toolResult")
             continue;
-        if (message.toolName !== "ask_operator" || message.isError !== true)
+        if (message.toolName !== ASK_OPERATOR_TOOL_NAME || message.isError !== true)
             continue;
         const content = message.content;
         if (!Array.isArray(content))
@@ -876,8 +949,16 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext, input.cloneEmitContext, {
         checks: input.stage.pre_emit_checks,
         readQaTrail: input.readQaTrail,
+        artifactPresence: {
+            runWorkspaceDir: roots.runWorkspaceDir,
+            stageId: runtimeStageId(input),
+            attempt: roots.attempt ?? 1,
+        },
     }, input.feedbackLoopEmitContext);
-    const emitTool = defineTool(emitDef);
+    const emitTool = defineTool({
+        ...emitDef,
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
+    });
     const gateKinds = input.stage.gate_kinds;
     const includeAsk = Array.isArray(gateKinds) && gateKinds.length > 0;
     const askDef = includeAsk
@@ -886,13 +967,21 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             allowedKinds: gateKinds,
         })
         : undefined;
-    const askTool = askDef ? defineTool(askDef) : undefined;
+    const askTool = askDef
+        ? defineTool({
+            ...askDef,
+            constrainedSampling: { type: "json_schema", strict: "prefer" },
+        })
+        : undefined;
     const artifactDef = createWriteStageArtifactTool({
         runWorkspaceDir: roots.runWorkspaceDir,
         stageId: runtimeStageId(input),
         attempt: roots.attempt ?? 1,
     });
-    const artifactTool = defineTool(artifactDef);
+    const artifactTool = defineTool({
+        ...artifactDef,
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
+    });
     if (input.stage.skill !== undefined && input.skillFilePath === undefined) {
         return {
             ok: false,
@@ -926,9 +1015,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                 modelsPath: path.join(path.dirname(roots.authPath), "models.json"),
             }
             : undefined);
-        const settingsManager = SettingsManager.inMemory({
-            compaction: { enabled: false },
-        });
+        const settingsManager = createPiSettingsManager();
         attached = await attachIsolatedMcp(input.resolvedMcpServers, {
             lifecycle: "eager",
         });
@@ -937,6 +1024,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             restoreProvider?.();
             return { ok: false, reason };
         };
+        const contextWiring = createSessionContextWiring({ workingState: true });
         const extensionFactories = [
             {
                 name: STAGEFLOW_PATH_DENY_EXTENSION_NAME,
@@ -960,22 +1048,25 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                     runWorkspaceDir: roots.runWorkspaceDir,
                     stageId: runtimeStageId(input),
                     attempt: roots.attempt ?? 1,
+                    turnCapped: new Set(["read", "bash"]),
                     exempt: new Set([
                         "read",
                         "bash",
+                        ...contextWiring.budgetExemptNames,
                         emitDef.name,
                         artifactDef.name,
-                        askDef?.name ?? "ask_operator",
+                        askDef?.name ?? ASK_OPERATOR_TOOL_NAME,
                     ]),
                 }),
             },
+            ...contextWiring.extensions,
             ...(attached.extensionFactories ?? []),
         ];
         const loader = createSealedResourceLoader({
             cwd: roots.cwd,
             agentDir: roots.agentDir,
             settingsManager,
-            systemPrompt: input.stage.system_prompt,
+            systemPrompt: composeStagePiSystemPrompt(input, emitDef.name, provider?.emitToolHint?.(emitDef.name), artifactDef.name),
             additionalExtensionPaths,
             ...(additionalSkillPaths.length > 0 ? { additionalSkillPaths } : {}),
             extensionFactories,
@@ -1020,7 +1111,8 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         const customTools = askTool
             ? [emitTool, askTool, artifactTool]
             : [emitTool, artifactTool];
-        const tools = resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? "ask_operator", gateKinds);
+        const tools = resolveStageToolNames(emitDef.name, artifactDef.name, askDef?.name ?? ASK_OPERATOR_TOOL_NAME, gateKinds);
+        tools.push(...contextWiring.toolNames);
         if (attached.extensionFactories !== undefined) {
             const mcpTools = collectMcpExtensionToolNames(loader);
             if (!mcpTools.ok) {
@@ -1030,12 +1122,18 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
         }
         if (input.channels && input.stage.channels?.some(channel => channel.operations.includes("send"))) {
             const definition = createSendMessageTool(input.channels);
-            customTools.push(defineTool(definition));
+            customTools.push(defineTool({
+                ...definition,
+                constrainedSampling: { type: "json_schema", strict: "prefer" },
+            }));
             tools.push(definition.name);
         }
         if (input.memory) {
             for (const definition of memorySession(input.memory).tools) {
-                customTools.push(defineTool(definition));
+                customTools.push(defineTool({
+                    ...definition,
+                    constrainedSampling: { type: "json_schema", strict: "prefer" },
+                }));
                 tools.push(definition.name);
             }
         }
@@ -1050,7 +1148,10 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             ];
             for (const definition of definitions)
                 if (definition) {
-                    customTools.push(defineTool(definition));
+                    customTools.push(defineTool({
+                        ...definition,
+                        constrainedSampling: { type: "json_schema", strict: "prefer" },
+                    }));
                     tools.push(definition.name);
                 }
         }
@@ -1060,8 +1161,10 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                 ...(roots.containerDockerBin !== undefined
                     ? { dockerBin: roots.containerDockerBin }
                     : {}),
+                ...(roots.readonlyDir !== undefined ? { readonlyDir: roots.readonlyDir } : {}),
             };
-            customTools.push(defineTool(createSandboxReadTool(sandboxTools)), defineTool(createSandboxWriteTool(sandboxTools)), defineTool(createSandboxEditTool(sandboxTools)), defineTool(createSandboxBashTool(sandboxTools)));
+            const sampling = { type: "json_schema", strict: "prefer" };
+            customTools.push(defineTool({ ...createSandboxReadTool(sandboxTools), constrainedSampling: sampling }), defineTool({ ...createSandboxWriteTool(sandboxTools), constrainedSampling: sampling }), defineTool({ ...createSandboxEditTool(sandboxTools), constrainedSampling: sampling }), defineTool({ ...createSandboxBashTool(sandboxTools), constrainedSampling: sampling }));
         }
         return {
             sessionManager,
@@ -1073,7 +1176,6 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             emitDefName: emitDef.name,
             ...(askDef ? { askOperatorDefName: askDef.name } : {}),
             artifactDefName: artifactDef.name,
-            providerEmitHint: provider?.emitToolHint?.(emitDef.name),
             restoreProvider,
             capture,
             usage,
@@ -1415,8 +1517,7 @@ export class PiAgentAdapter {
                         await session.prompt(composeTimeoutResumePrompt());
                         return;
                     }
-                    const userPrompt = composeStageUserPrompt(input, wiring.emitDefName, wiring.providerEmitHint, wiring.artifactDefName);
-                    await session.prompt(userPrompt);
+                    await session.prompt(composeStagePiKickoffPrompt(input));
                 });
             },
             resume: resumeWaiting

package/dist/agent/piSettings.d.ts

@@ -0,0 +1,7 @@
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+/**
+ * Settings for every Pi session Stageflow starts. Auto-compaction is always on
+ * and not configurable: a long session compacts at the threshold, and recovers
+ * once from a provider context-overflow, instead of failing.
+ */
+export declare function createPiSettingsManager(): SettingsManager;

package/dist/agent/piSettings.js

@@ -0,0 +1,9 @@
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+/**
+ * Settings for every Pi session Stageflow starts. Auto-compaction is always on
+ * and not configurable: a long session compacts at the threshold, and recovers
+ * once from a provider context-overflow, instead of failing.
+ */
+export function createPiSettingsManager() {
+    return SettingsManager.inMemory({ compaction: { enabled: true } });
+}

package/dist/agent/sandboxPiTools.d.ts

@@ -1,6 +1,8 @@
 import { Type } from "typebox";
 import { type SandboxFileTarget } from "../runtime/sandboxFiles.js";
-export type SandboxPiToolOptions = SandboxFileTarget;
+export type SandboxPiToolOptions = SandboxFileTarget & {
+    readonlyDir?: string;
+};
 export declare function createSandboxReadTool(options: SandboxPiToolOptions): {
     name: string;
     label: string;

package/dist/agent/sandboxPiTools.js

@@ -89,9 +89,15 @@ export function createSandboxBashTool(options) {
     return {
         name: "bash",
         label: "bash",
-        description: "Execute a bash command in this stage's sandbox. The working directory is /workspace. The host filesystem is not mounted.",
+        description: options.readonlyDir
+            ? `Execute a bash command in this stage's sandbox. The working directory is /workspace. One folder is mounted read-only at ${options.readonlyDir}. Read files there. If a file is missing, stop. Do not create a stand-in.`
+            : "Execute a bash command in this stage's sandbox. The working directory is /workspace. The host filesystem is not mounted.",
         promptSnippet: "Execute bash commands in /workspace",
-        promptGuidelines: ["The shell starts in /workspace. Do not use host paths."],
+        promptGuidelines: [
+            options.readonlyDir
+                ? `The shell starts in /workspace. The only host folder you can read is ${options.readonlyDir}, and it is read-only. If a file is not there, stop. Do not create stand-in documents.`
+                : "The shell starts in /workspace. Do not use host paths.",
+        ],
         parameters: Type.Object({
             command: Type.String({ description: "Shell command to execute" }),
             timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),

package/dist/agent/stageTurnDriver.d.ts

@@ -1,6 +1,13 @@
 import type { EmitCapture } from "../tools/emitStageEnvelope.js";
-/** Follow-up turns sent when the agent ends its turn without an accepted envelope. */
+/**
+ * Follow-up turns in a row, with no progress between them, sent when the agent ends its turn
+ * without an accepted envelope. A reminder turn that runs a tool call counts as progress and
+ * resets this budget.
+ */
 export declare const DEFAULT_EMIT_REMINDERS = 2;
+/** Hard ceiling on reminders in one stage attempt, however much progress each one made. */
+export declare const MAX_TOTAL_EMIT_REMINDERS = 20;
+export declare const LEAKED_TOOL_CALL_ERROR = "the model wrote its tool call out as plain text instead of making it, even after reminders. This is usually a provider-side tool-call parsing problem (for example one OpenRouter backend serving the model). Run again, pin a different provider for this model, or choose another model.";
 /** The slice of a Pi session the driver needs; a fake in tests. */
 export type StageTurnSession = {
     prompt(text: string): Promise<void>;
@@ -24,7 +31,9 @@ export declare function formatProviderError(text: string | undefined): string;
  * 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;
+/** True when the last assistant turn wrote a tool call out as plain text instead of making a real one. */
+export declare function lastTurnLeakedToolCall(messages: readonly unknown[]): boolean;
+export declare function emitReminderPrompt(emitToolName: string, attempt: number, max: number, rejectedEmit?: string, leakedToolCall?: boolean): 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,

package/dist/agent/stageTurnDriver.js

@@ -1,6 +1,13 @@
-/** Follow-up turns sent when the agent ends its turn without an accepted envelope. */
+/**
+ * Follow-up turns in a row, with no progress between them, sent when the agent ends its turn
+ * without an accepted envelope. A reminder turn that runs a tool call counts as progress and
+ * resets this budget.
+ */
 export const DEFAULT_EMIT_REMINDERS = 2;
+/** Hard ceiling on reminders in one stage attempt, however much progress each one made. */
+export const MAX_TOTAL_EMIT_REMINDERS = 20;
 const PROVIDER_ERROR_MAX_CHARS = 500;
+export const LEAKED_TOOL_CALL_ERROR = "the model wrote its tool call out as plain text instead of making it, even after reminders. This is usually a provider-side tool-call parsing problem (for example one OpenRouter backend serving the model). Run again, pin a different provider for this model, or choose another model.";
 function lastAssistant(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
         const m = messages[i];
@@ -27,10 +34,37 @@ export function lastTurnProviderError(messages) {
 function lastTurnAborted(messages) {
     return lastAssistant(messages)?.stopReason === "aborted";
 }
-export function emitReminderPrompt(emitToolName, attempt, max, rejectedEmit) {
+const LEAKED_TOOL_CALL = /<[|｜]?\s*tool[▁_ ]?calls?[▁_ ]?(begin|start)|<tool_call>|<function_calls?>/i;
+/** True when the last assistant turn wrote a tool call out as plain text instead of making a real one. */
+export function lastTurnLeakedToolCall(messages) {
+    const m = lastAssistant(messages);
+    if (!m || !Array.isArray(m.content))
+        return false;
+    return m.content.some((block) => {
+        if (block.type === "toolCall")
+            return false;
+        const text = typeof block.text === "string" ? block.text : typeof block.thinking === "string" ? block.thinking : "";
+        return LEAKED_TOOL_CALL.test(text);
+    });
+}
+/** Tool calls the agent made in the messages after `fromIndex`. */
+function toolCallsSince(messages, fromIndex) {
+    let count = 0;
+    for (const raw of messages.slice(fromIndex)) {
+        const m = raw;
+        if (m?.role !== "assistant" || !Array.isArray(m.content))
+            continue;
+        count += m.content.filter((block) => block.type === "toolCall").length;
+    }
+    return count;
+}
+export function emitReminderPrompt(emitToolName, attempt, max, rejectedEmit, leakedToolCall = false) {
     const lines = [
         `Reminder ${attempt} of ${max}: your turn ended without an accepted ${emitToolName} call, so this stage has not finished.`,
     ];
+    if (leakedToolCall) {
+        lines.push(`Your last tool call was written out as plain text, so it was NOT run. Make it again as a real tool call.`);
+    }
     if (rejectedEmit !== undefined) {
         lines.push(`Your last ${emitToolName} call was rejected: ${rejectedEmit}`);
         lines.push(`Fix that and call ${emitToolName} again.`);
@@ -49,16 +83,23 @@ export function emitReminderPrompt(emitToolName, attempt, max, rejectedEmit) {
 export async function remindUntilEmitted(session, capture, options) {
     const max = options.maxReminders ?? DEFAULT_EMIT_REMINDERS;
     let reminders = 0;
+    let withoutProgress = 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) {
+        if (options.shouldStop() || lastTurnAborted(session.messages))
             return { reminders };
+        if (withoutProgress >= max || reminders >= MAX_TOTAL_EMIT_REMINDERS) {
+            return lastTurnLeakedToolCall(session.messages) ? { reminders, providerError: LEAKED_TOOL_CALL_ERROR } : { reminders };
         }
         reminders++;
-        await session.prompt(emitReminderPrompt(options.emitToolName, reminders, max, capture.error));
+        withoutProgress++;
+        const before = session.messages.length;
+        await session.prompt(emitReminderPrompt(options.emitToolName, withoutProgress, max, capture.error, lastTurnLeakedToolCall(session.messages)));
+        if (toolCallsSince(session.messages, before) > 0)
+            withoutProgress = 0;
     }
 }

package/dist/agent/toolOutputBudget.d.ts

@@ -16,7 +16,7 @@ export type BudgetInput = {
     knownTokens: number | null;
     turnLedgerTokens: number;
 };
-export type SpillReason = "exceeds_remaining" | "exceeds_per_result_cap" | "unknown_usage_fallback" | "adapter_truncated";
+export type SpillReason = "exceeds_remaining" | "exceeds_per_result_cap" | "unknown_usage_fallback" | "adapter_truncated" | "turn_cap_deferred";
 export type BudgetDecision = {
     kind: "inline";
     estTokens: number;
@@ -27,6 +27,20 @@ export type BudgetDecision = {
 };
 export declare function estimateTokens(bytes: number): number;
 export declare function decideToolOutput(input: BudgetInput): BudgetDecision;
+export declare const TURN_TOTAL_MAX_FRACTION = 0.4;
+export type TurnCapInput = {
+    resultTokens: number;
+    contextWindow: number;
+    knownTokens: number | null;
+    turnLedgerTokens: number;
+};
+/**
+ * Turn cap for tools whose output is kept inline (read, bash): the first result
+ * of a turn always passes so a lone call can make progress; later results in
+ * the same turn are deferred once the turn's total would pass the smaller of
+ * the remaining window (after the reserve) and TURN_TOTAL_MAX_FRACTION of it.
+ */
+export declare function decideTurnCap(input: TurnCapInput): "inline" | "defer";
 export declare function utf8ByteLength(text: string): number;
 export declare function truncateUtf8(text: string, maxBytes: number): string;
 export declare function tryParseJson(text: string): {

package/dist/agent/toolOutputBudget.js

@@ -31,6 +31,24 @@ export function decideToolOutput(input) {
     }
     return { kind: "inline", estTokens };
 }
+export const TURN_TOTAL_MAX_FRACTION = 0.4;
+/**
+ * Turn cap for tools whose output is kept inline (read, bash): the first result
+ * of a turn always passes so a lone call can make progress; later results in
+ * the same turn are deferred once the turn's total would pass the smaller of
+ * the remaining window (after the reserve) and TURN_TOTAL_MAX_FRACTION of it.
+ */
+export function decideTurnCap(input) {
+    const window = input.contextWindow;
+    if (input.knownTokens === null || !Number.isFinite(window) || window <= 0)
+        return "inline";
+    if (input.turnLedgerTokens <= 0)
+        return "inline";
+    const reserve = Math.max(RESERVE_MIN_TOKENS, RESERVE_FRACTION * window);
+    const remaining = window - input.knownTokens - reserve;
+    const allowed = Math.min(remaining, TURN_TOTAL_MAX_FRACTION * window);
+    return input.turnLedgerTokens + input.resultTokens > allowed ? "defer" : "inline";
+}
 export function utf8ByteLength(text) {
     return Buffer.byteLength(text, "utf8");
 }

package/dist/agent/toolOutputBudgetExtension.d.ts

@@ -16,6 +16,8 @@ export type ToolOutputBudgetOptions = {
     stageId: string;
     attempt: number;
     exempt: ReadonlySet<string>;
+    /** Exempt tools that keep output inline but share the per-turn token cap (read, bash). */
+    turnCapped?: ReadonlySet<string>;
     onSpill?: (event: ToolOutputSpillEvent) => void;
 };
 export declare function formatSpillNotice(spilled: SpilledToolOutput, estTokens: number, lostReason?: string): string;

package/dist/agent/toolOutputBudgetExtension.js

@@ -1,4 +1,4 @@
-import { buildPreview, decideToolOutput, estimateTokens, IMAGE_BLOCK_EST_TOKENS, truncateUtf8, UNKNOWN_USAGE_INLINE_MAX_BYTES, utf8ByteLength, } from "./toolOutputBudget.js";
+import { buildPreview, decideToolOutput, decideTurnCap, estimateTokens, IMAGE_BLOCK_EST_TOKENS, truncateUtf8, UNKNOWN_USAGE_INLINE_MAX_BYTES, utf8ByteLength, } from "./toolOutputBudget.js";
 import { spillToolOutput } from "./toolOutputSpill.js";
 import { discardAdapterSpill, readAdapterSpill } from "./adapterSpill.js";
 export const STAGEFLOW_TOOL_OUTPUT_EXTENSION_NAME = "stageflow-tool-output";
@@ -37,11 +37,48 @@ export function createToolOutputBudgetExtension(options) {
             }
             return undefined;
         });
-        pi.on("tool_result", async (event, ctx) => {
-            if (options.exempt.has(event.toolName))
+        const capTurnTotal = (event, ctx) => {
+            const images = event.content.filter((block) => block.type === "image");
+            const resultTokens = estimateTokens(utf8ByteLength(joinText(event.content))) +
+                images.length * IMAGE_BLOCK_EST_TOKENS;
+            const usage = ctx.getContextUsage();
+            const verdict = decideTurnCap({
+                resultTokens,
+                contextWindow: usage?.contextWindow ?? 0,
+                knownTokens: usage?.tokens ?? null,
+                turnLedgerTokens,
+            });
+            if (verdict === "inline") {
+                turnLedgerTokens += resultTokens;
                 return undefined;
+            }
+            const notice = event.toolName === "bash"
+                ? `[bash output not returned: this turn's tool results already fill the context budget (this one is ~${resultTokens} tokens). The command already ran; do not run it again. Re-read its output with a read-only command (for example write it to a file earlier, or use grep/head/tail on the files it produced) in a later turn, and keep to one large call per turn.]`
+                : `[${event.toolName} output not returned: this turn's tool results already fill the context budget (this one is ~${resultTokens} tokens). Nothing was lost. Call ${event.toolName} again for this one on its own, in a later turn, and keep to one large ${event.toolName} call per turn.]`;
+            turnLedgerTokens += estimateTokens(utf8ByteLength(notice));
+            options.onSpill?.({
+                toolName: event.toolName,
+                toolCallId: event.toolCallId,
+                reason: "turn_cap_deferred",
+                originalBytes: utf8ByteLength(joinText(event.content)),
+                estTokens: resultTokens,
+            });
+            const previousDetails = event.details !== null && typeof event.details === "object"
+                ? event.details
+                : {};
+            return {
+                content: [{ type: "text", text: notice }],
+                details: { ...previousDetails, stageflowToolOutput: { deferred: true, estTokens: resultTokens } },
+            };
+        };
+        pi.on("tool_result", async (event, ctx) => {
             if (event.parentToolCallId !== undefined)
                 return undefined;
+            if (options.exempt.has(event.toolName)) {
+                if (!options.turnCapped?.has(event.toolName))
+                    return undefined;
+                return capTurnTotal(event, ctx);
+            }
             const images = event.content.filter((block) => block.type === "image");
             turnLedgerTokens += images.length * IMAGE_BLOCK_EST_TOKENS;
             const visible = joinText(event.content);

package/dist/agents/authorChat.d.ts

@@ -9,6 +9,7 @@ export type AgentAuthorTurnResult = {
     summaryLines: SummaryLine[];
 };
 export declare function resetAgentAuthorSessionsForTests(): void;
+export declare function forgetAgentAuthorSession(sessionId: string): void;
 export declare function runAgentAuthorTurn(input: {
     host: OperatorAgentHost;
     projectRoot: string;

package/dist/agents/authorChat.js

@@ -53,6 +53,13 @@ export function resetAgentAuthorSessionsForTests() {
         session.close();
     sessions.clear();
 }
+export function forgetAgentAuthorSession(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return;
+    session.close();
+    sessions.delete(sessionId);
+}
 export async function runAgentAuthorTurn(input) {
     const message = input.message.trim();
     if (!message)

package/dist/agents/authorSessionStore.d.ts

@@ -25,11 +25,14 @@ export declare function createAuthorSession(input?: {
 }, storeRoot?: string): AuthorSessionRecord;
 export declare function readAuthorSession(sessionId: string, storeRoot?: string): AuthorSessionRecord | null;
 export declare function saveAuthorSession(record: AuthorSessionRecord, storeRoot?: string): AuthorSessionRecord;
+/** Removes the session directory. Returns false when the id is invalid or missing. */
+export declare function deleteAuthorSession(sessionId: string, storeRoot?: string): boolean;
 export type AuthorDraftSummary = {
     id: string;
     name: string;
     updatedAt: string;
     messages: number;
 };
+export declare function draftHasWork(record: AuthorSessionRecord): boolean;
 /** Unsaved author sessions, newest first. Empty shells with no name and no chat are left out. */
 export declare function listAuthorDrafts(storeRoot?: string): AuthorDraftSummary[];