@stigmer/runner 3.0.1

package/src/middleware/cost-cap.ts

@@ -0,0 +1,213 @@
+/**
+ * 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";
+import type { StigmerMiddleware, CostCapConfig } from "./types.js";
+
+const DEFAULT_WARNING_PCT = 80;
+const MIN_WARNING_PCT = 50;
+const MAX_WARNING_PCT = 95;
+
+export interface CostCapMiddleware extends StigmerMiddleware {
+  readonly runningCost: number;
+  readonly exceeded: boolean;
+  forSubAgent(): StigmerMiddleware;
+}
+
+interface UsageMetadata {
+  input_tokens?: number;
+  output_tokens?: number;
+  input_token_details?: { cache_read?: number } | null;
+}
+
+function extractUsage(aiMessage: Record<string, unknown>): {
+  totalInput: number; output: number; cacheRead: number;
+} {
+  const usage = (aiMessage as { usage_metadata?: UsageMetadata }).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: CostCapConfig): CostCapMiddleware {
+  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: number, output: number, cacheRead: number): number {
+    let inputCost: number;
+    let cacheCost: number;
+
+    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(): SystemMessage {
+    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(): SystemMessage {
+    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: Record<string, unknown>): { messages: SystemMessage[] } | void {
+    if (exceeded) return;
+
+    const messages = (state.messages ?? []) as unknown[];
+    let lastAi: Record<string, unknown> | null = null;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i] as { _getType?: () => string };
+      if (msg?._getType?.() === "ai") {
+        lastAi = msg as Record<string, unknown>;
+        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: Parameters<NonNullable<StigmerMiddleware["wrapToolCall"]>>[0],
+    handler: Parameters<NonNullable<StigmerMiddleware["wrapToolCall"]>>[1],
+  ) {
+    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: CostCapMiddleware = {
+    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(): StigmerMiddleware {
+      return {
+        name: "CostCapSubAgentView",
+        // Sub-agent view does NOT reset state on beforeAgent
+        afterModel(state) { return processAfterModel(state); },
+        wrapToolCall: processWrapToolCall,
+      };
+    },
+  };
+
+  return middleware;
+}

package/src/middleware/error-hints.ts

@@ -0,0 +1,136 @@
+/**
+ * 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";
+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 function enrichErrorMessage(toolName: string, error: string): string {
+  const hints: string[] = [];
+  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(): StigmerMiddleware {
+  return {
+    name: "ErrorHintsMiddleware",
+
+    async wrapToolCall(request, handler) {
+      try {
+        return await handler(request);
+      } catch (err: unknown) {
+        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,
+        });
+      }
+    },
+  };
+}

package/src/middleware/execution-budget.ts

@@ -0,0 +1,176 @@
+/**
+ * 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";
+import type { StigmerMiddleware, ExecutionBudgetConfig } from "./types.js";
+
+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: readonly string[] = [
+  "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: number, warningPct: number): number {
+  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: Partial<ExecutionBudgetConfig> = {},
+): StigmerMiddleware {
+  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: SystemMessage | null = null;
+
+  function createThresholdWarning(): SystemMessage {
+    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(): SystemMessage {
+    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(): void {
+    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 as unknown[]), 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}`,
+        );
+      }
+    },
+  };
+}

package/src/middleware/graceful-stop.ts

@@ -0,0 +1,86 @@
+/**
+ * Platform-level graceful stop middleware.
+ *
+ * Activated externally when the platform signals the runner to stop
+ * (e.g. via ExecutionControlSignal.STOP from the updateStatus RPC).
+ * Once activated, blocks all tool execution and gives the model one
+ * final tool-free round to produce a summary.
+ *
+ * Always injected into the agent graph. Inert until activate() is called.
+ */
+
+import { ToolMessage, SystemMessage } from "@langchain/core/messages";
+import type { StigmerMiddleware } from "./types.js";
+
+const DEFAULT_STOP_MESSAGE =
+  "The platform has requested this execution to stop. All tool calls are " +
+  "now blocked. Respond with a concise summary of what you accomplished " +
+  "and what work remains so the user can continue in their next session.";
+
+export interface GracefulStopMiddleware extends StigmerMiddleware {
+  readonly activated: boolean;
+  activate(reason?: string): void;
+  forSubAgent(): StigmerMiddleware;
+}
+
+export function createGracefulStopMiddleware(): GracefulStopMiddleware {
+  let _activated = false;
+  let _messageInjected = false;
+  let _reason = "";
+
+  const middleware: GracefulStopMiddleware = {
+    name: "GracefulStopMiddleware",
+
+    get activated() {
+      return _activated;
+    },
+
+    activate(reason = "") {
+      if (!_activated) {
+        _activated = true;
+        _reason = reason;
+        console.warn(
+          `[PLATFORM_STOP] GracefulStopMiddleware activated (reason=${reason || "unspecified"})`,
+        );
+      }
+    },
+
+    afterModel() {
+      if (!_activated || _messageInjected) return;
+      _messageInjected = true;
+      const msg = _reason || DEFAULT_STOP_MESSAGE;
+      return { messages: [new SystemMessage({ content: msg })] };
+    },
+
+    async wrapToolCall(request, handler) {
+      if (!_activated) return handler(request);
+
+      console.log(
+        `[PLATFORM_STOP] Blocking tool '${request.toolCall.name}' (id=${request.toolCall.id})`,
+      );
+      return new ToolMessage({
+        content:
+          "[Execution stopped by platform: tool execution blocked. " +
+          "Summarize your progress for the user.]",
+        tool_call_id: request.toolCall.id,
+        name: request.toolCall.name,
+      });
+    },
+
+    forSubAgent(): StigmerMiddleware {
+      return {
+        name: "GracefulStopSubAgentView",
+
+        afterModel() {
+          return middleware.afterModel!({} as any, {});
+        },
+
+        async wrapToolCall(request, handler) {
+          return middleware.wrapToolCall!(request, handler);
+        },
+      };
+    },
+  };
+
+  return middleware;
+}

package/src/middleware/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Middleware stack factory.
+ *
+ * Assembles the ordered middleware array from a MiddlewareStackConfig.
+ * The composition order matches the Python create_deep_agent injection:
+ *
+ *   1. Loop detection (always)
+ *   2. Execution budget (always)
+ *   3. Tool truncation (always)
+ *   4. Graceful stop (always, inert until activated)
+ *   5. Cost cap (conditional: only when maxCostUsd > 0)
+ *   6. Error hints (always)
+ *   7. OTel spans (always, no-op when OTel not configured)
+ */
+
+import type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
+import type { GracefulStopMiddleware } from "./graceful-stop.js";
+import { createLoopDetectionMiddleware } from "./loop-detection.js";
+import { createExecutionBudgetMiddleware } from "./execution-budget.js";
+import { createToolTruncationMiddleware } from "./tool-truncation.js";
+import { createGracefulStopMiddleware } from "./graceful-stop.js";
+import { createApprovalGateMiddleware } from "./approval-gate.js";
+import { createCostCapMiddleware, type CostCapMiddleware } from "./cost-cap.js";
+import { createErrorHintsMiddleware } from "./error-hints.js";
+import { createOtelSpansMiddleware } from "./otel-spans.js";
+
+export { createThinkTool } from "./think-tool.js";
+export type { GracefulStopMiddleware } from "./graceful-stop.js";
+export type { CostCapMiddleware } from "./cost-cap.js";
+export type { StigmerMiddleware, MiddlewareStackConfig } from "./types.js";
+
+export interface MiddlewareStackResult {
+  readonly middleware: StigmerMiddleware[];
+  readonly gracefulStop: GracefulStopMiddleware;
+  readonly costCap: CostCapMiddleware | null;
+}
+
+export function buildMiddlewareStack(
+  config: MiddlewareStackConfig = {},
+): MiddlewareStackResult {
+  const stack: StigmerMiddleware[] = [];
+
+  stack.push(createLoopDetectionMiddleware(config.loopDetection));
+
+  stack.push(createExecutionBudgetMiddleware(config.executionBudget));
+
+  stack.push(createToolTruncationMiddleware(config.toolTruncation));
+
+  const gracefulStop = createGracefulStopMiddleware();
+  stack.push(gracefulStop);
+
+  if (config.approvalGate) {
+    stack.push(createApprovalGateMiddleware(config.approvalGate));
+  }
+
+  if (config.costCap && config.costCap.maxCostUsd > 0) {
+    const costCapMiddleware = createCostCapMiddleware(config.costCap);
+    stack.push(costCapMiddleware);
+
+    stack.push(createErrorHintsMiddleware());
+    stack.push(createOtelSpansMiddleware(config.otelSpans));
+
+    return { middleware: stack, gracefulStop, costCap: costCapMiddleware };
+  }
+
+  stack.push(createErrorHintsMiddleware());
+  stack.push(createOtelSpansMiddleware(config.otelSpans));
+
+  return { middleware: stack, gracefulStop, costCap: null };
+}