@stigmer/runner 3.0.1

package/dist/middleware/approval-gate.js

@@ -0,0 +1,125 @@
+/**
+ * Approval gate middleware for HITL (human-in-the-loop) tool approval.
+ *
+ * Checks each tool call against the merged approval policy. When a tool
+ * requires approval, calls LangGraph `interrupt()` to pause the graph
+ * at the checkpoint. The Temporal workflow then waits for the user's
+ * decision via the `approvalGateResolved` signal.
+ *
+ * On resume, LangGraph restarts the node from the beginning. The
+ * `interrupt()` call returns the user's decision (approve/skip/reject)
+ * from the `Command(resume=...)` payload.
+ *
+ * Idempotency: Because the node restarts on resume, this middleware
+ * will be invoked again for the same tool call. The `interrupt()` call
+ * is idempotent — on resume it returns the decision value instead of
+ * pausing again.
+ *
+ * Platform tool defaults: DeepAgents JS backend tools (read, write,
+ * edit, execute, etc.) are not covered by MCP policy chains. This
+ * middleware applies sensible defaults: read-only tools are auto-approved,
+ * mutating tools require approval when no explicit policy exists.
+ */
+import { ToolMessage } from "@langchain/core/messages";
+import { interrupt } from "@langchain/langgraph";
+import { resolveApprovalMessage, } from "../shared/approval-policy.js";
+const SAFE_PLATFORM_TOOLS = new Set([
+    "read", "read_file",
+    "ls", "list_directory",
+    "glob", "find_files",
+    "grep", "search", "ripgrep",
+    "think",
+]);
+const DANGEROUS_PLATFORM_TOOLS = new Map([
+    ["write", "Write file: {{args.path}}"],
+    ["write_file", "Write file: {{args.path}}"],
+    ["edit", "Edit file: {{args.path}}"],
+    ["edit_file", "Edit file: {{args.path}}"],
+    ["create", "Create file: {{args.path}}"],
+    ["create_file", "Create file: {{args.path}}"],
+    ["delete", "Delete: {{args.path}}"],
+    ["delete_file", "Delete file: {{args.path}}"],
+    ["execute", "Execute command: {{args.command}}"],
+    ["shell", "Execute shell command: {{args.command}}"],
+    ["str_replace_editor", "Edit file: {{args.path}}"],
+]);
+export function createApprovalGateMiddleware(config) {
+    const { policies, autoApproveAll, toolServerMap } = config;
+    if (autoApproveAll) {
+        return { name: "ApprovalGateMiddleware" };
+    }
+    return {
+        name: "ApprovalGateMiddleware",
+        async wrapToolCall(request, handler) {
+            const { toolCall } = request;
+            const toolName = toolCall.name;
+            const serverSlug = toolServerMap.get(toolName) ?? "";
+            const requirement = resolveToolApproval(toolName, serverSlug, toolCall.args, policies);
+            if (!requirement.requiresApproval) {
+                return await handler(request);
+            }
+            const approvalRequest = {
+                tool_call_id: toolCall.id,
+                tool_name: toolName,
+                mcp_server_slug: serverSlug,
+                message: requirement.message,
+            };
+            const response = interrupt(approvalRequest);
+            const action = (typeof response === "object" && response !== null
+                ? (response.action ?? "")
+                : "").toString().toLowerCase();
+            if (action === "approve") {
+                return await handler(request);
+            }
+            if (action === "skip") {
+                const comment = response.comment ?? "";
+                const skipMessage = comment
+                    ? `Tool '${toolName}' was skipped by user: ${comment}. Please proceed without this operation.`
+                    : `Tool '${toolName}' was skipped by user. Please proceed without this operation.`;
+                return new ToolMessage({
+                    content: skipMessage,
+                    tool_call_id: toolCall.id,
+                    name: toolName,
+                });
+            }
+            if (action === "reject") {
+                const comment = response.comment ?? "rejected by user";
+                return new ToolMessage({
+                    content: `Tool '${toolName}' was rejected: ${comment}. Execution will be terminated.`,
+                    tool_call_id: toolCall.id,
+                    name: toolName,
+                });
+            }
+            return new ToolMessage({
+                content: `Tool '${toolName}' approval returned unknown action: '${action}'. Treating as skip.`,
+                tool_call_id: toolCall.id,
+                name: toolName,
+            });
+        },
+    };
+}
+function resolveToolApproval(toolName, serverSlug, args, policies) {
+    if (serverSlug) {
+        const key = `${serverSlug}/${toolName}`;
+        const policy = policies.get(key);
+        if (policy) {
+            return {
+                requiresApproval: policy.requiresApproval,
+                message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
+            };
+        }
+        return { requiresApproval: false, message: "" };
+    }
+    if (SAFE_PLATFORM_TOOLS.has(toolName)) {
+        return { requiresApproval: false, message: "" };
+    }
+    const dangerousTemplate = DANGEROUS_PLATFORM_TOOLS.get(toolName);
+    if (dangerousTemplate) {
+        return {
+            requiresApproval: true,
+            message: resolveApprovalMessage(dangerousTemplate, toolName, args),
+        };
+    }
+    return { requiresApproval: false, message: "" };
+}
+//# sourceMappingURL=approval-gate.js.map

package/dist/middleware/approval-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gate.js","sourceRoot":"","sources":["../../src/middleware/approval-gate.ts"],"names":[],"mappings":"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"}

package/dist/middleware/cost-cap.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cost cap middleware for agent execution budget enforcement.
+ *
+ * Tracks running estimated cost of LLM calls and enforces a
+ * configurable cost ceiling:
+ *
+ * afterModel — extracts usage_metadata from the latest AIMessage,
+ *   computes incremental cost, accumulates a running total. Injects
+ *   a warning SystemMessage at ~80% and a termination message at 100%.
+ *
+ * wrapToolCall — blocks all tool execution when the budget is exceeded,
+ *   giving the model one final tool-free round to produce a summary.
+ *
+ * Only injected when maxCostUsd > 0 is explicitly configured.
+ */
+import type { StigmerMiddleware, CostCapConfig } from "./types.js";
+export interface CostCapMiddleware extends StigmerMiddleware {
+    readonly runningCost: number;
+    readonly exceeded: boolean;
+    forSubAgent(): StigmerMiddleware;
+}
+export declare function createCostCapMiddleware(config: CostCapConfig): CostCapMiddleware;

package/dist/middleware/cost-cap.js

@@ -0,0 +1,159 @@
+/**
+ * Cost cap middleware for agent execution budget enforcement.
+ *
+ * Tracks running estimated cost of LLM calls and enforces a
+ * configurable cost ceiling:
+ *
+ * afterModel — extracts usage_metadata from the latest AIMessage,
+ *   computes incremental cost, accumulates a running total. Injects
+ *   a warning SystemMessage at ~80% and a termination message at 100%.
+ *
+ * wrapToolCall — blocks all tool execution when the budget is exceeded,
+ *   giving the model one final tool-free round to produce a summary.
+ *
+ * Only injected when maxCostUsd > 0 is explicitly configured.
+ */
+import { ToolMessage, SystemMessage } from "@langchain/core/messages";
+const DEFAULT_WARNING_PCT = 80;
+const MIN_WARNING_PCT = 50;
+const MAX_WARNING_PCT = 95;
+function extractUsage(aiMessage) {
+    const usage = aiMessage.usage_metadata;
+    if (!usage)
+        return { totalInput: 0, output: 0, cacheRead: 0 };
+    const totalInput = usage.input_tokens ?? 0;
+    const output = usage.output_tokens ?? 0;
+    const details = usage.input_token_details;
+    const cacheRead = (details && typeof details === "object")
+        ? (details.cache_read ?? 0)
+        : 0;
+    return { totalInput, output, cacheRead };
+}
+export function createCostCapMiddleware(config) {
+    const { maxCostUsd, inputPricePerMillion, outputPricePerMillion, cacheReadPricePerMillion, } = config;
+    const warningPct = config.warningPct ?? DEFAULT_WARNING_PCT;
+    if (maxCostUsd <= 0)
+        throw new Error(`maxCostUsd must be positive, got ${maxCostUsd}`);
+    if (warningPct < MIN_WARNING_PCT || warningPct > MAX_WARNING_PCT) {
+        throw new Error(`warningPct must be between ${MIN_WARNING_PCT} and ${MAX_WARNING_PCT}, got ${warningPct}`);
+    }
+    let runningCost = 0;
+    let warned = false;
+    let exceeded = false;
+    let modelCallCount = 0;
+    function computeCallCost(totalInput, output, cacheRead) {
+        let inputCost;
+        let cacheCost;
+        if (cacheReadPricePerMillion > 0 && cacheRead > 0) {
+            const regularInput = Math.max(totalInput - cacheRead, 0);
+            inputCost = regularInput * inputPricePerMillion;
+            cacheCost = cacheRead * cacheReadPricePerMillion;
+        }
+        else {
+            inputCost = totalInput * inputPricePerMillion;
+            cacheCost = 0;
+        }
+        const outputCost = output * outputPricePerMillion;
+        return (inputCost + cacheCost + outputCost) / 1_000_000;
+    }
+    function createWarningMessage() {
+        const pct = maxCostUsd > 0 ? (runningCost / maxCostUsd * 100) : 0;
+        const remaining = Math.max(maxCostUsd - runningCost, 0);
+        return new SystemMessage({
+            content: `Budget warning: This execution has consumed ` +
+                `$${runningCost.toFixed(4)} of the $${maxCostUsd.toFixed(2)} ` +
+                `budget (${pct.toFixed(0)}%). ` +
+                `Approximately $${remaining.toFixed(4)} remaining. ` +
+                `Prioritize completing your current task. Summarize results ` +
+                `and any remaining work so the user can continue in the next message.`,
+        });
+    }
+    function createExceededMessage() {
+        return new SystemMessage({
+            content: `Budget exceeded: This execution has consumed ` +
+                `$${runningCost.toFixed(4)}, exceeding the ` +
+                `$${maxCostUsd.toFixed(2)} budget. ` +
+                `All tool calls are now blocked. ` +
+                `Respond with a summary of what you accomplished and ` +
+                `what work remains so the user can continue.`,
+        });
+    }
+    function processAfterModel(state) {
+        if (exceeded)
+            return;
+        const messages = (state.messages ?? []);
+        let lastAi = null;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg?._getType?.() === "ai") {
+                lastAi = msg;
+                break;
+            }
+        }
+        if (!lastAi)
+            return;
+        const { totalInput, output, cacheRead } = extractUsage(lastAi);
+        if (totalInput === 0 && output === 0)
+            return;
+        const callCost = computeCallCost(totalInput, output, cacheRead);
+        runningCost += callCost;
+        modelCallCount++;
+        const warningThreshold = maxCostUsd * warningPct / 100;
+        if (runningCost >= maxCostUsd) {
+            exceeded = true;
+            console.warn(`[CostCap] EXCEEDED: $${runningCost.toFixed(4)} >= $${maxCostUsd.toFixed(2)} ` +
+                `after ${modelCallCount} calls. Tool execution will be blocked.`);
+            return { messages: [createExceededMessage()] };
+        }
+        if (!warned && runningCost >= warningThreshold) {
+            warned = true;
+            console.warn(`[CostCap] WARNING: $${runningCost.toFixed(4)} >= $${warningThreshold.toFixed(4)} ` +
+                `(${warningPct}% of $${maxCostUsd.toFixed(2)}) after ${modelCallCount} calls.`);
+            return { messages: [createWarningMessage()] };
+        }
+    }
+    async function processWrapToolCall(request, handler) {
+        if (exceeded) {
+            return new ToolMessage({
+                content: `[Budget exceeded: tool execution blocked. ` +
+                    `Summarize your progress for the user.]`,
+                tool_call_id: request.toolCall.id,
+                name: request.toolCall.name,
+            });
+        }
+        return await handler(request);
+    }
+    const middleware = {
+        name: "CostCapMiddleware",
+        get runningCost() { return runningCost; },
+        get exceeded() { return exceeded; },
+        beforeAgent() {
+            runningCost = 0;
+            warned = false;
+            exceeded = false;
+            modelCallCount = 0;
+        },
+        afterModel(state) {
+            return processAfterModel(state);
+        },
+        wrapToolCall: processWrapToolCall,
+        afterAgent() {
+            const pctUsed = maxCostUsd > 0
+                ? (runningCost / maxCostUsd * 100)
+                : 0;
+            console.log(`[CostCap] Summary: $${runningCost.toFixed(4)} of $${maxCostUsd.toFixed(2)} ` +
+                `(~${pctUsed.toFixed(0)}%) across ${modelCallCount} calls, ` +
+                `warned=${warned}, exceeded=${exceeded}`);
+        },
+        forSubAgent() {
+            return {
+                name: "CostCapSubAgentView",
+                // Sub-agent view does NOT reset state on beforeAgent
+                afterModel(state) { return processAfterModel(state); },
+                wrapToolCall: processWrapToolCall,
+            };
+        },
+    };
+    return middleware;
+}
+//# sourceMappingURL=cost-cap.js.map

package/dist/middleware/cost-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-cap.js","sourceRoot":"","sources":["../../src/middleware/cost-cap.ts"],"names":[],"mappings":"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"}

package/dist/middleware/error-hints.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error message enrichment for agent resilience.
+ *
+ * Two exports:
+ * 1. enrichErrorMessage() — pure utility that pattern-matches tool errors
+ *    to actionable recovery hints.
+ * 2. createErrorHintsMiddleware() — wrapToolCall middleware that catches
+ *    tool execution errors and enriches the ToolMessage with hints.
+ *
+ * Zero external dependencies beyond LangChain messages.
+ */
+import type { StigmerMiddleware } from "./types.js";
+/**
+ * Enrich an error message with contextual recovery hints.
+ *
+ * Analyzes the error string and tool name to produce actionable
+ * suggestions that help the LLM try alternative approaches.
+ */
+export declare function enrichErrorMessage(toolName: string, error: string): string;
+/**
+ * Create middleware that enriches tool execution errors with recovery hints.
+ *
+ * Wraps every tool call in a try/catch. On error, produces a ToolMessage
+ * with the enriched error text instead of letting the error propagate
+ * as a raw string.
+ */
+export declare function createErrorHintsMiddleware(): StigmerMiddleware;

package/dist/middleware/error-hints.js

@@ -0,0 +1,116 @@
+/**
+ * Error message enrichment for agent resilience.
+ *
+ * Two exports:
+ * 1. enrichErrorMessage() — pure utility that pattern-matches tool errors
+ *    to actionable recovery hints.
+ * 2. createErrorHintsMiddleware() — wrapToolCall middleware that catches
+ *    tool execution errors and enriches the ToolMessage with hints.
+ *
+ * Zero external dependencies beyond LangChain messages.
+ */
+import { ToolMessage } from "@langchain/core/messages";
+/**
+ * Enrich an error message with contextual recovery hints.
+ *
+ * Analyzes the error string and tool name to produce actionable
+ * suggestions that help the LLM try alternative approaches.
+ */
+export function enrichErrorMessage(toolName, error) {
+    const hints = [];
+    const errorLower = error.toLowerCase();
+    const toolLower = toolName.toLowerCase();
+    if (errorLower.includes("not found") || errorLower.includes("no such file")) {
+        hints.push("Try using ls or glob to discover available files/resources");
+        hints.push("Check if the path is correct — use ls on the parent directory");
+        hints.push("The file might be in a different location — search with glob patterns");
+    }
+    if (errorLower.includes("permission") || errorLower.includes("access denied")) {
+        hints.push("Check if the path is correct and accessible");
+        hints.push("Verify you have the right permissions for this operation");
+        hints.push("Try an alternative location if the target is read-only");
+    }
+    if (errorLower.includes("text to replace not found")) {
+        hints.push("Re-read the file with the read tool to see its current contents");
+        hints.push("The file content may have changed — use the actual text from read output");
+        hints.push("Check for whitespace differences (tabs vs spaces, trailing newlines)");
+        hints.push("If the exact text cannot be matched, use write to replace the entire file");
+    }
+    if (toolLower.includes("edit") || toolLower.includes("write")) {
+        hints.push("Try reading the target first to understand its current state");
+        hints.push("If editing fails, try read + modify + write as a complete replacement");
+    }
+    if (errorLower.includes("auth") || errorLower.includes("unauthorized") || errorLower.includes("403")) {
+        hints.push("Verify authentication credentials are correct");
+        hints.push("Check if the token has expired or lacks required permissions");
+    }
+    if (errorLower.includes("connection") || errorLower.includes("timeout") || errorLower.includes("unavailable")) {
+        hints.push("This may be a transient error — wait a moment and retry");
+        hints.push("Check if the service is available");
+    }
+    if (errorLower.includes("invalid") || errorLower.includes("malformed") || errorLower.includes("format")) {
+        hints.push("Review the parameter format and types");
+        hints.push("Try with simplified or default parameters first");
+    }
+    if (errorLower.includes("rpc error") || errorLower.includes("grpc")) {
+        if (errorLower.includes("not found") || errorLower.includes("notfound")) {
+            hints.push("The requested resource does not exist on the platform yet");
+            hints.push("Use a list or search tool to discover existing resources");
+        }
+        if (errorLower.includes("permission denied") || errorLower.includes("permissiondenied")) {
+            hints.push("The API key or credentials lack permission for this operation");
+        }
+        if (errorLower.includes("unavailable")) {
+            hints.push("The backend service is temporarily unreachable — wait and retry");
+        }
+    }
+    if (errorLower.includes("not found") &&
+        (errorLower.includes("org") || errorLower.includes("slug") ||
+            errorLower.includes("server") || errorLower.includes("environment"))) {
+        hints.push("Verify the org and slug/name values are correct");
+        hints.push("The resource may not have been created yet");
+        hints.push("Use a list operation to see what exists in the current org/environment");
+    }
+    if (errorLower.includes("rate") || errorLower.includes("limit") ||
+        errorLower.includes("quota") || errorLower.includes("429")) {
+        hints.push("Wait a moment before retrying — rate limits reset over time");
+        hints.push("Try reducing the scope of your request");
+    }
+    if (hints.length > 0) {
+        const recovery = hints.map(h => `- ${h}`).join("\n");
+        return `Error: ${error}\n\nRecovery suggestions:\n${recovery}`;
+    }
+    return (`Error: ${error}\n\n` +
+        "Recovery suggestions:\n" +
+        "- Analyze the error message for clues about what went wrong\n" +
+        "- Try a different approach or alternative tool\n" +
+        "- Verify your inputs and assumptions are correct");
+}
+/**
+ * Create middleware that enriches tool execution errors with recovery hints.
+ *
+ * Wraps every tool call in a try/catch. On error, produces a ToolMessage
+ * with the enriched error text instead of letting the error propagate
+ * as a raw string.
+ */
+export function createErrorHintsMiddleware() {
+    return {
+        name: "ErrorHintsMiddleware",
+        async wrapToolCall(request, handler) {
+            try {
+                return await handler(request);
+            }
+            catch (err) {
+                const errorMessage = err instanceof Error ? err.message : String(err);
+                const toolName = request.toolCall.name;
+                const enriched = enrichErrorMessage(toolName, errorMessage);
+                return new ToolMessage({
+                    content: enriched,
+                    tool_call_id: request.toolCall.id,
+                    name: toolName,
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=error-hints.js.map

package/dist/middleware/error-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-hints.js","sourceRoot":"","sources":["../../src/middleware/error-hints.ts"],"names":[],"mappings":"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"}

package/dist/middleware/execution-budget.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Execution budget middleware for autonomous agents.
+ *
+ * Two operating modes:
+ *
+ * Threshold mode (default, warningInterval=null):
+ *   Fires a single SystemMessage at a computed percentage of the
+ *   LangGraph recursion limit.
+ *
+ * Periodic mode (warningInterval set):
+ *   Fires a SystemMessage every N model rounds with escalating urgency,
+ *   up to maxWarnings times.
+ *
+ * Uses wrapModelCall (not afterModel) to safely prepend advisory
+ * messages to the model's input, avoiding the AIMessage/ToolMessage
+ * ordering violation that would occur if we injected between a
+ * tool_use AIMessage and its corresponding ToolMessage.
+ */
+import type { StigmerMiddleware, ExecutionBudgetConfig } from "./types.js";
+export declare function createExecutionBudgetMiddleware(config?: Partial<ExecutionBudgetConfig>): StigmerMiddleware;

package/dist/middleware/execution-budget.js

@@ -0,0 +1,151 @@
+/**
+ * Execution budget middleware for autonomous agents.
+ *
+ * Two operating modes:
+ *
+ * Threshold mode (default, warningInterval=null):
+ *   Fires a single SystemMessage at a computed percentage of the
+ *   LangGraph recursion limit.
+ *
+ * Periodic mode (warningInterval set):
+ *   Fires a SystemMessage every N model rounds with escalating urgency,
+ *   up to maxWarnings times.
+ *
+ * Uses wrapModelCall (not afterModel) to safely prepend advisory
+ * messages to the model's input, avoiding the AIMessage/ToolMessage
+ * ordering violation that would occur if we injected between a
+ * tool_use AIMessage and its corresponding ToolMessage.
+ */
+import { SystemMessage } from "@langchain/core/messages";
+const DEFAULT_RECURSION_LIMIT = 6000;
+const DEFAULT_WARNING_PCT = 80;
+const MIN_WARNING_PCT = 50;
+const MAX_WARNING_PCT = 95;
+const MIN_ROUNDS_BEFORE_WARNING = 3;
+const PERIODIC_MESSAGES = [
+    "You have been working for {rounds} model rounds. " +
+        "If your task is nearing completion, start wrapping up. " +
+        "Summarize progress so far and outline any remaining steps.",
+    "Extended execution: {rounds} model rounds. " +
+        "Prioritize completing your current task now. " +
+        "Summarize results and any remaining work so the user can " +
+        "continue in the next message.",
+    "Long-running execution: {rounds} model rounds. " +
+        "Wrap up your work — provide your findings and conclude. " +
+        "If you cannot finish, summarize what you accomplished and what remains.",
+    "Critical: {rounds} model rounds reached. " +
+        "Provide your final answer immediately with whatever " +
+        "information you have gathered. Do not start new tool calls " +
+        "unless absolutely essential to your conclusion.",
+];
+function computeWarningRound(recursionLimit, warningPct) {
+    const estimatedTotalRounds = Math.floor(recursionLimit / 6);
+    const threshold = Math.floor(estimatedTotalRounds * warningPct / 100);
+    return Math.max(threshold, MIN_ROUNDS_BEFORE_WARNING);
+}
+export function createExecutionBudgetMiddleware(config = {}) {
+    const recursionLimit = config.recursionLimit ?? DEFAULT_RECURSION_LIMIT;
+    const warningPct = config.warningPct ?? DEFAULT_WARNING_PCT;
+    const warningInterval = config.warningInterval ?? null;
+    const maxWarnings = config.maxWarnings ?? 4;
+    const isPeriodic = warningInterval !== null;
+    if (isPeriodic) {
+        if (warningInterval <= 0)
+            throw new Error(`warningInterval must be positive, got ${warningInterval}`);
+        if (maxWarnings <= 0)
+            throw new Error(`maxWarnings must be positive, got ${maxWarnings}`);
+    }
+    else {
+        if (warningPct < MIN_WARNING_PCT || warningPct > MAX_WARNING_PCT) {
+            throw new Error(`warningPct must be between ${MIN_WARNING_PCT} and ${MAX_WARNING_PCT}, got ${warningPct}`);
+        }
+        if (recursionLimit <= 0)
+            throw new Error(`recursionLimit must be positive, got ${recursionLimit}`);
+    }
+    let modelRoundCount = 0;
+    let warningCount = 0;
+    let nextWarningRound = isPeriodic
+        ? warningInterval
+        : computeWarningRound(recursionLimit, warningPct);
+    let pendingAdvisory = null;
+    function createThresholdWarning() {
+        const estimatedTotal = Math.floor(recursionLimit / 6);
+        const remaining = Math.max(estimatedTotal - modelRoundCount, 0);
+        return new SystemMessage({
+            content: `You are approaching the step limit for this message ` +
+                `(approximately ${warningPct}% used, ~${remaining} rounds remaining). ` +
+                `Prioritize completing your current task. Summarize results ` +
+                `and any remaining work so the user can continue in the next message.`,
+        });
+    }
+    function createPeriodicWarning() {
+        const idx = Math.min(warningCount, PERIODIC_MESSAGES.length) - 1;
+        const template = PERIODIC_MESSAGES[Math.max(idx, 0)];
+        return new SystemMessage({
+            content: template.replace("{rounds}", String(modelRoundCount)),
+        });
+    }
+    function evaluateBudget() {
+        if (isPeriodic) {
+            if (warningCount >= maxWarnings)
+                return;
+            if (modelRoundCount >= nextWarningRound) {
+                warningCount++;
+                nextWarningRound += warningInterval;
+                console.warn(`[ExecutionBudget] Advisory ${warningCount}/${maxWarnings}: ` +
+                    `round ${modelRoundCount} (interval=${warningInterval})`);
+                pendingAdvisory = createPeriodicWarning();
+            }
+        }
+        else {
+            if (warningCount > 0)
+                return;
+            if (modelRoundCount >= nextWarningRound) {
+                warningCount = 1;
+                const estimatedTotal = Math.floor(recursionLimit / 6);
+                console.warn(`[ExecutionBudget] WARNING: round ${modelRoundCount} of ~${estimatedTotal} ` +
+                    `(~${warningPct}% of recursion_limit=${recursionLimit})`);
+                pendingAdvisory = createThresholdWarning();
+            }
+        }
+    }
+    return {
+        name: "ExecutionBudgetMiddleware",
+        beforeAgent() {
+            modelRoundCount = 0;
+            warningCount = 0;
+            pendingAdvisory = null;
+            nextWarningRound = isPeriodic
+                ? warningInterval
+                : computeWarningRound(recursionLimit, warningPct);
+        },
+        async wrapModelCall(request, handler) {
+            let effectiveRequest = request;
+            if (pendingAdvisory !== null) {
+                const advisory = pendingAdvisory;
+                pendingAdvisory = null;
+                const messages = [...request.messages, advisory];
+                effectiveRequest = { ...request, messages };
+            }
+            const response = await handler(effectiveRequest);
+            modelRoundCount++;
+            evaluateBudget();
+            return response;
+        },
+        afterAgent() {
+            if (isPeriodic) {
+                console.log(`[ExecutionBudget] Summary (periodic): ${modelRoundCount} model rounds, ` +
+                    `${warningCount}/${maxWarnings} advisories (interval=${warningInterval})`);
+            }
+            else {
+                const estimatedTotal = Math.floor(recursionLimit / 6);
+                const pctUsed = estimatedTotal > 0
+                    ? Math.floor(modelRoundCount * 100 / estimatedTotal)
+                    : 0;
+                console.log(`[ExecutionBudget] Summary (threshold): ${modelRoundCount} rounds ` +
+                    `of ~${estimatedTotal} (~${pctUsed}% used), warnings=${warningCount}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=execution-budget.js.map