{"record":{"id":"3b9e523fc5f88f10","repo":"paperclipai/paperclip","slug":"agent-turn-limit-exceeded","errorCode":null,"errorMessage":"agent turn limit exceeded","messagePattern":"agent turn limit exceeded","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/cli/eval-session.ts","lineNumber":243,"sourceCode":"): EvalSessionUsage | null {\n  if (!snapshot?.usageLedger?.length) return null;\n  try {\n    return evalSessionUsage(request.model, snapshot);\n  } catch {\n    return null;\n  }\n}\n\nexport function boundedEvalSessionUsage(\n  request: EvalSessionRequest,\n  turn: CapabilityLiveTurnResult,\n): EvalSessionUsage | null {\n  if (turn.status !== \"completed\") {\n    return usageIfAvailable(request, turn.snapshot);\n  }\n  const usage = evalSessionUsage(request.model, turn.snapshot);\n  if (usage.agentTurns > request.limits.maxAgentTurns) {\n    throw new Error(\"agent turn limit exceeded\");\n  }\n  if (\n    usage.estimatedCostNanodollars >\n    request.limits.maxEstimatedCostNanodollars\n  ) {\n    throw new Error(\"estimated cost limit exceeded\");\n  }\n  if (\n    usage.providerReportedCostNanodollars >\n    request.limits.maxEstimatedCostNanodollars\n  ) {\n    throw new Error(\"provider-reported cost limit exceeded\");\n  }\n  return usage;\n}\n\nasync function closeSession(\n  session: CapabilityLiveSession | null,","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/cli/eval-session.ts#L225-L261","documentation":"runEvalSessionCli enforces per-run budget limits after the provider turn completes. It computes usage from the turn snapshot via evalSessionUsage and throws when the agent consumed more agent turns than request.limits.maxAgentTurns allows. This is an intentional fail-fast guard so an eval session cannot exceed its resource budget.","triggerScenarios":"A completed provider turn's snapshot reports usage.agentTurns > request.limits.maxAgentTurns in runEvalSessionCli — e.g. a task/prompt that required more agentic iterations (tool calls, retries, multi-step reasoning) than the configured cap.","commonSituations":"Eval harness configured with too low maxAgentTurns for the task complexity; prompts that force many tool-use round trips; a provider/model that loops or re-tries internally, inflating turn counts; limits copied from a simpler benchmark.","solutions":["Raise request.limits.maxAgentTurns in the eval request to a value appropriate for the task","Shorten or simplify the prompt so fewer agentic turns are needed","Switch to a model/provider that completes the task in fewer turns","Inspect the turn snapshot to confirm the turn count is real and not caused by an internal retry loop"],"exampleFix":"// before\nlimits: { maxAgentTurns: 5, ... }\n// after\nlimits: { maxAgentTurns: 20, ... }","handlingStrategy":"validation","validationCode":"import { evalSessionUsage } from \"./eval-session-usage.js\";\nconst projectedTurns = 1 + Math.ceil(request.prompt.length / 2000); // rough pre-flight floor\nif (projectedTurns >= request.limits.maxAgentTurns) {\n  throw new Error(`maxAgentTurns=${request.limits.maxAgentTurns} too low for this task; raise the limit before running`);\n}\n// after the turn, before it throws:\nconst usage = evalSessionUsage(request.model, turn.snapshot);\nif (usage.agentTurns > request.limits.maxAgentTurns) {\n  console.warn(`agent turns ${usage.agentTurns} exceed limit ${request.limits.maxAgentTurns}; raising limit or simplifying task`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runEvalSessionCli(request, cli);\n} catch (error) {\n  if (error instanceof Error && error.message === \"agent turn limit exceeded\") {\n    request.limits.maxAgentTurns = Math.ceil(request.limits.maxAgentTurns * 2);\n    return runEvalSessionCli(request, cli);\n  }\n  throw error;\n}","preventionTips":["Size maxAgentTurns against the hardest task in the eval set, not the average","Log evalSessionUsage per run to calibrate limits empirically","Alert on runs that finish near the limit — they will exceed it soon"],"tags":["limit","budget","eval"],"backgroundTag":"agent-turn-limit-exceeded","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}