feat(agent): add run limits for spend, steps, and duration

apps/docs/content/docs/workflows/blocks/agent.mdx

@@ -121,7 +121,7 @@ Set **Response Format** to a JSON Schema when later blocks need named fields. Na
 
 Malformed JSON can fall back to plain text with `_responseFormatWarning`. Sim does not perform a general post-parse schema check on every provider result, so validate fields downstream before consequential actions.
 
-Avoid schema fields named `model`, `tokens`, `toolCalls`, `providerTiming`, or `cost`. Sim's standard metadata overwrites those fields after parsing, even when a metadata value is absent.
+Avoid schema fields named `model`, `tokens`, `toolCalls`, `providerTiming`, or `cost`. Sim's standard metadata overwrites those fields after parsing, even when a metadata value is absent. With **Limit run** on, `stopReason` is overwritten too.
 
 ```json
 {
@@ -144,6 +144,7 @@ Some settings live under advanced, or appear only for models that support them:
 
 - **Temperature.** Controls variation on models that support it. Lower values tend to reduce variation; test accuracy on representative inputs rather than treating temperature as a factuality guarantee.
 - **Max output tokens.** Caps the response length. Defaults to the model's full limit.
+- **Limit run.** Stops a long tool-using run at a **max spend** in USD, a **max number of steps**, or a **max duration** in seconds. A step is one model response whose tool calls run. Leave a field empty for no limit. A limit acts only when the agent wants to keep using tools, so a call or tool that is already running finishes first, and a run that finishes before reaching a limit is unaffected. Spend is measured the same way as `<agent.cost>`, including tool costs, so a model Sim does not bill for, such as one on your own API key, adds only its tool costs. One budget covers the selected model and its fallbacks, and each try of **Retry on fail** starts a new one. **When a limit is reached** chooses what happens: **Return best answer** (the default) asks the model for a final answer without tools, which can spend slightly past the limit, and fails the block only if the model keeps calling tools anyway; **Fail block** fails the block if the agent asks for more tools. `<agent.stopReason>` reports whether a limit stopped the run.
 - **Reasoning effort / Thinking level.** Controls supported models' reasoning budget. Higher settings can increase latency and token use; evaluate the result on your task.
 - **Prompt caching.** Reuses a stable system prompt and tool definitions on supported Claude models. Sim uses a five-minute cache. Cache-write pricing, read discounts, and minimum prefix length depend on the model; check [Anthropic's current requirements](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations). Enable it for repeated runs sharing a prefix; a one-off run can pay a write premium without a later cache hit.
 - **API key.** Your key for the chosen provider. Hidden when hosted Sim supplies a key for the selected model, including Jev.
@@ -163,6 +164,7 @@ After the agent runs, later blocks read its result by name:
 | `<agent.toolCalls>` | The tools the agent called, with their inputs and results |
 | `<agent.model>` | The model that ran the step |
 | `<agent.cost>` | Estimated cost in USD, as an object with `input`, `output`, and `total`; read `<agent.cost.total>` for the total |
+| `<agent.stopReason>` | With **Limit run** on: `completed`, or the limit that stopped the run: `spend_limit`, `step_limit`, or `time_limit` |
 
 The cost object can include additional fields such as tool costs or pricing. The Logs UI and run-resource API use credits. See [Costs](/platform/costs) for units and billing behavior.
 

apps/sim/blocks/blocks/agent.ts

@@ -1,7 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { AgentIcon } from '@/components/icons'
 import { getModelFallbackSubBlock, MODEL_FALLBACK_INPUTS } from '@/blocks/model-fallbacks'
-import type { BlockConfig } from '@/blocks/types'
+import type { BlockConfig, SubBlockConfig } from '@/blocks/types'
 import { AuthMode, IntegrationType } from '@/blocks/types'
 import {
   getAgentModelOptions,
@@ -42,6 +42,12 @@ const MODELS_WITHOUT_MEMORY = getModelsWithoutMemory()
 const EVALUATION_MODELS = getEvaluationModels()
 const MODELS_WITHOUT_CHAT_CONTROLS = [...MODELS_WITH_DEEP_RESEARCH, ...EVALUATION_MODELS]
 
+const RUN_LIMIT_FIELD_CONDITION: SubBlockConfig['condition'] = {
+  field: 'runLimits',
+  value: true,
+  and: { field: 'model', value: MODELS_WITHOUT_CHAT_CONTROLS, not: true },
+}
+
 // Helper function to get the tool ID from a block type
 const getToolIdFromBlock = (blockType: string): string | undefined => {
   try {
@@ -422,6 +428,56 @@ Return ONLY the JSON array.`,
         not: true,
       },
     },
+    {
+      id: 'runLimits',
+      title: 'Limit run',
+      type: 'switch',
+      description:
+        'A step is one model response whose tool calls run. Limits stop the agent from starting new steps; a call or tool already running finishes first. Spend is measured like the cost output, tools included.',
+      defaultValue: false,
+      mode: 'advanced',
+      condition: {
+        field: 'model',
+        value: MODELS_WITHOUT_CHAT_CONTROLS,
+        not: true,
+      },
+    },
+    {
+      id: 'maxRunCost',
+      title: 'Max spend (USD)',
+      type: 'short-input',
+      placeholder: 'No limit',
+      mode: 'advanced',
+      condition: RUN_LIMIT_FIELD_CONDITION,
+    },
+    {
+      id: 'maxSteps',
+      title: 'Max steps',
+      type: 'short-input',
+      placeholder: 'No limit',
+      mode: 'advanced',
+      condition: RUN_LIMIT_FIELD_CONDITION,
+    },
+    {
+      id: 'maxRunDuration',
+      title: 'Max duration (seconds)',
+      type: 'short-input',
+      placeholder: 'No limit',
+      mode: 'advanced',
+      condition: RUN_LIMIT_FIELD_CONDITION,
+    },
+    {
+      id: 'onRunLimit',
+      title: 'When a limit is reached',
+      type: 'dropdown',
+      options: [
+        { label: 'Return best answer', id: 'finalize' },
+        { label: 'Fail block', id: 'fail' },
+      ],
+      defaultValue: 'finalize',
+      mode: 'advanced',
+      condition: RUN_LIMIT_FIELD_CONDITION,
+    },
     {
       id: 'responseFormat',
       title: 'Response Format',
@@ -614,6 +670,24 @@ Return ONLY the JSON array.`,
       type: 'boolean',
       description: 'Cache the system prompt and tool definitions on models that support it',
     },
+    runLimits: {
+      type: 'boolean',
+      description: 'Stop the agent at the spend, step, and duration limits below',
+    },
+    maxRunCost: { type: 'number', description: 'Most this block may be billed, in USD' },
+    maxSteps: {
+      type: 'number',
+      description: 'Most model responses whose tool calls may run',
+    },
+    maxRunDuration: {
+      type: 'number',
+      description: 'Seconds after which the agent starts no new steps',
+    },
+    onRunLimit: {
+      type: 'string',
+      description:
+        'When the agent still wants tools past a limit: finalize to answer without them, or fail to fail the block',
+    },
     ...MODEL_FALLBACK_INPUTS,
     tools: { type: 'json', description: 'Available tools configuration' },
     skills: { type: 'json', description: 'Selected skills configuration' },
@@ -634,6 +708,11 @@ Return ONLY the JSON array.`,
       description: 'Provider timing information',
     },
     cost: { type: 'json', description: 'Cost of the API call' },
+    stopReason: {
+      type: 'string',
+      description: 'Why the agent stopped: completed, spend_limit, step_limit, or time_limit',
+      condition: { field: 'runLimits', value: true },
+    },
     interactionId: {
       type: 'string',
       description: 'Interaction ID for multi-turn deep research follow-ups',

apps/sim/executor/execution/block-executor.ts

@@ -1423,6 +1423,9 @@ export class BlockExecutor {
             providerTiming: executionOutput.providerTiming,
             cost: executionOutput.cost,
             model: executionOutput.model,
+            ...(executionOutput.stopReason !== undefined && {
+              stopReason: executionOutput.stopReason,
+            }),
           }
           parsedForFormat = true
         } catch (error) {

apps/sim/executor/handlers/agent/handler.ts

@@ -57,7 +57,7 @@ import {
 import { getAllBlocks, getBlock } from '@/blocks'
 import { assembleCustomBlockInputMapping, isCustomBlockType } from '@/blocks/custom/build-config'
 import type { BlockOutput } from '@/blocks/types'
-import { normalizeFileInput } from '@/blocks/utils'
+import { normalizeFileInput, parseOptionalNumberInput } from '@/blocks/utils'
 import {
   assertPermissionsAllowed,
   validateBlockType,
@@ -126,6 +126,7 @@ import {
   getInlineHydrationMaxBytes,
 } from '@/providers/file-attachments.server'
 import { isAutoModel, isEvaluationModel, SIM_AUTO_MODEL_ID } from '@/providers/models'
+import { AgentRunLimits } from '@/providers/run-limits'
 import { isRunAbortError } from '@/providers/streaming-tool-loop-shared'
 import {
   type ProviderToolInputProvenance,
@@ -231,6 +232,7 @@ interface ExecuteAcrossModelsConfig {
   resultRegistry: ResolvedSecretTraceRegistry | undefined
   providerErrorRegistry: ResolvedSecretTraceRegistry | undefined
   agentConversation?: AgentTurnSession
+  runLimits?: AgentRunLimits
 }
 
 interface FormattedAgentTools {
@@ -519,6 +521,7 @@ export class AgentBlockHandler implements BlockHandler {
       }
 
       const streamingConfig = this.getStreamingConfig(ctx, block)
+      const runLimits = this.createRunLimits(filteredInputs)
       const agentConversation =
         filteredInputs.memoryType &&
         filteredInputs.memoryType !== 'none' &&
@@ -649,6 +652,7 @@ export class AgentBlockHandler implements BlockHandler {
         resultRegistry,
         providerErrorRegistry,
         agentConversation,
+        runLimits,
       })
       if (servedRegistry) ctx.resolvedSecretTraceRegistry = servedRegistry
 
@@ -667,6 +671,7 @@ export class AgentBlockHandler implements BlockHandler {
       if (this.isStreamingExecution(result)) {
         const streamingResult = result as StreamingExecution
         streamingResult.diagnosticResolvedSecretTraceRegistry = providerErrorRegistry
+        runLimits?.reportOn(streamingResult.execution.output)
         if (filteredInputs.memoryType && filteredInputs.memoryType !== 'none') {
           return this.wrapStreamForMemoryPersistence(
             ctx,
@@ -689,12 +694,30 @@ export class AgentBlockHandler implements BlockHandler {
         )
       }
 
+      if (runLimits && isRecordLike(result)) runLimits.reportOn(result)
       return result
     } finally {
       settlePrivateAgentSelectors()
     }
   }
 
+  /** The limits a block set while Limit run is on; parsed once and shared by every model it tries. */
+  private createRunLimits(inputs: AgentInputs): AgentRunLimits | undefined {
+    if (inputs.runLimits !== true) return undefined
+    const maxRunDuration = parseOptionalNumberInput(inputs.maxRunDuration, 'Max duration', {
+      min: 1,
+    })
+    return new AgentRunLimits({
+      maxCost: parseOptionalNumberInput(inputs.maxRunCost, 'Max spend', { min: 0.01 }),
+      maxSteps: parseOptionalNumberInput(inputs.maxSteps, 'Max steps', {
+        integer: true,
+        min: 1,
+      }),
+      maxDurationMs: maxRunDuration === undefined ? undefined : maxRunDuration * 1000,
+      onLimit: inputs.onRunLimit === 'fail' ? 'fail' : 'finalize',
+    })
+  }
+
   private resolveToolUsageControls(
     tools: ToolInput[],
     canonicalModes?: Record<string, 'basic' | 'advanced'>
@@ -2755,7 +2778,8 @@ export class AgentBlockHandler implements BlockHandler {
           config.responseFormat,
           resultRegistry,
           config.providerErrorRegistry,
-          config.agentConversation
+          config.agentConversation,
+          config.runLimits
         )
         if ((hasNext || config.retryPrimaryOnStreamStart) && this.isStreamingExecution(result)) {
           result = await this.primeStreamingExecution(result as StreamingExecution)
@@ -2974,7 +2998,8 @@ export class AgentBlockHandler implements BlockHandler {
     responseFormat: any,
     modelRuntimeRegistry: ResolvedSecretTraceRegistry | undefined,
     providerErrorRegistry: ResolvedSecretTraceRegistry | undefined,
-    agentConversation?: AgentTurnSession
+    agentConversation?: AgentTurnSession,
+    runLimits?: AgentRunLimits
   ): Promise<BlockOutput | StreamingExecution> {
     const providerId = providerRequest.provider
     const model = providerRequest.model
@@ -3056,6 +3081,7 @@ export class AgentBlockHandler implements BlockHandler {
           agentMemoryContext: agentConversation
             ? { historyTokens: providerRequest.memoryHistoryTokens }
             : undefined,
+          runLimits,
         }
       )
 

apps/sim/executor/handlers/agent/types.ts

@@ -50,6 +50,12 @@ export interface AgentInputs {
   verbosity?: string
   thinkingLevel?: string
   promptCaching?: boolean
+  // Run limits, applied only while `runLimits` is on
+  runLimits?: boolean
+  maxRunCost?: string | number
+  maxSteps?: string | number
+  maxRunDuration?: string | number
+  onRunLimit?: 'finalize' | 'fail'
   files?: unknown
   /** Ordered models tried when the request to `model` fails; see `normalizeFallbackModels`. */
   fallbackModels?: Array<Partial<FallbackModelEntry> & { model: string }>

apps/sim/providers/anthropic/core.ts

@@ -21,7 +21,7 @@ import {
   createReadableStreamFromAnthropicStream,
 } from '@/providers/anthropic/utils'
 import {
-  isConversationContextError,
+  isPermanentGenerationError,
   prepareConversationGeneration,
 } from '@/providers/conversation-generation'
 import {
@@ -1006,7 +1006,7 @@ export async function executeAnthropicProviderRequest(
       }
     )
 
-    if (isAbortError(error) || request.abortSignal?.aborted || isConversationContextError(error)) {
+    if (isAbortError(error) || request.abortSignal?.aborted || isPermanentGenerationError(error)) {
       throw error
     }
 

apps/sim/providers/azure-openai/index.ts

@@ -26,7 +26,7 @@ import {
   isResponsesEndpoint,
 } from '@/providers/azure-openai/utils'
 import {
-  isConversationContextError,
+  isPermanentGenerationError,
   prepareConversationGeneration,
 } from '@/providers/conversation-generation'
 import {
@@ -716,7 +716,7 @@ async function executeChatCompletionsRequest(
       }
     )
 
-    if (isAbortError(error) || request.abortSignal?.aborted || isConversationContextError(error)) {
+    if (isAbortError(error) || request.abortSignal?.aborted || isPermanentGenerationError(error)) {
       throw error
     }
 

apps/sim/providers/bedrock/index.ts

@@ -31,7 +31,7 @@ import {
 } from '@/providers/bedrock/utils'
 import { getCachedProviderClient } from '@/providers/client-cache'
 import {
-  isConversationContextError,
+  isPermanentGenerationError,
   prepareConversationGeneration,
 } from '@/providers/conversation-generation'
 import {
@@ -1060,7 +1060,7 @@ export const bedrockProvider: ProviderConfig = {
       if (
         isAbortError(error) ||
         request.abortSignal?.aborted ||
-        isConversationContextError(error)
+        isPermanentGenerationError(error)
       ) {
         throw error
       }

apps/sim/providers/cerebras/index.ts

@@ -7,7 +7,7 @@ import { MAX_TOOL_ITERATIONS } from '@/providers'
 import { formatMessagesForProvider } from '@/providers/attachments'
 import type { CerebrasResponse } from '@/providers/cerebras/types'
 import {
-  isConversationContextError,
+  isPermanentGenerationError,
   prepareConversationGeneration,
 } from '@/providers/conversation-generation'
 import {
@@ -676,7 +676,7 @@ export const cerebrasProvider: ProviderConfig = {
       if (
         isAbortError(error) ||
         request.abortSignal?.aborted ||
-        isConversationContextError(error)
+        isPermanentGenerationError(error)
       ) {
         throw error
       }

apps/sim/providers/conversation-generation.ts

@@ -21,6 +21,7 @@ import {
   isConversationHistoryNotice,
 } from '@/providers/conversation-metadata'
 import { getConversationModelLimits } from '@/providers/conversation-model'
+import { applyRunLimits, RunLimitError } from '@/providers/run-limits'
 import { assertRunWithinUsageLimit, RunUsageLimitError } from '@/providers/run-usage-limit'
 import { isAbortError } from '@/providers/streaming-tool-loop-shared'
 import type { Message, ProviderRequest } from '@/providers/types'
@@ -117,13 +118,15 @@ function contextError(message: string): Error {
 
 /**
  * Provider wrappers must preserve the permanent failures this module raises, context faults and
- * the run's usage-limit stop, so fallback cannot restart them and the stop keeps its billed cost.
+ * the run's usage-limit and run-limit stops, so fallback cannot restart them and a stop keeps its
+ * billed cost.
  */
-export function isConversationContextError(error: unknown): boolean {
+export function isPermanentGenerationError(error: unknown): boolean {
   return (
     error instanceof AgentContextLimitError ||
     error instanceof AgentContextProtocolError ||
-    error instanceof RunUsageLimitError
+    error instanceof RunUsageLimitError ||
+    error instanceof RunLimitError
   )
 }
 
@@ -288,10 +291,11 @@ function nativeSummaryMessage(summary: Message, protocol: ConversationProtocol):
 export async function prepareConversationGeneration<T>(
   request: ProviderRequest,
   protocol: ConversationProtocol,
-  payload: T
+  requestedPayload: T
 ): Promise<T> {
   const runtime = getConversationRequestContext(request)
   await assertRunWithinUsageLimit(runtime)
+  const payload = applyRunLimits(runtime, request, protocol, requestedPayload)
   if (!runtime?.agentConversation) return payload
   request.abortSignal?.throwIfAborted()
   if (!isRecordLike(payload))