{"record":{"id":"676977a844d0fad0","repo":"JuliusBrussee/caveman","slug":"event-code-event-message","errorCode":null,"errorMessage":"<event.code>: <event.message>","messagePattern":"<event\\.code>: <event\\.message>","errorType":"exception","errorClass":"CavemanRunError","httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":998,"sourceCode":"async function runAgentWithOptions(\n  definition: AgentDefinition,\n  input: string,\n  options: InternalRunOptions,\n  executionContext: InternalExecutionContext,\n): Promise<RunResult> {\n  let final: RunResult | undefined;\n  for await (const event of streamAgentWithOptions(\n    definition,\n    input,\n    options,\n    executionContext,\n  )) {\n    if (event.type === \"run_end\") final = event.result;\n    if (event.type === \"run_error\") {\n      // The ledger is not lost on the throwing path either: the partial receipt\n      // rides on a typed `cause` so a caller that only awaits the promise can\n      // still read what was spent before the failure.\n      throw new CavemanRunError(event.code, event.message, event.receipt);\n    }\n  }\n  if (!final) throw new Error(\"caveman agent: run ended without terminal evidence\");\n  return final;\n}\n\nexport function streamAgent(\n  definition: AgentDefinition,\n  input: string,\n  options: RunOptions = {},\n): AsyncGenerator<CavemanRunEvent> {\n  rejectInternalRunOptions(options);\n  return streamAgentWithOptions(\n    definition,\n    input,\n    options,\n    rootExecutionContext(definition, options.maxCostUsd, options),\n  );","sourceCodeStart":980,"sourceCodeEnd":1016,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/runtime.ts#L980-L1016","documentation":"runAgentWithOptions throws CavemanRunError built from the stream's run_error event, carrying the event's code and message plus the partial spend receipt as cause. This is the awaited-promise surface for run failures; the message shown is '<event.code>: <event.message>' with the actual event values substituted.","triggerScenarios":"The run stream emits a run_error event for any internal failure (budget exhaustion, breaker trip, provider error, tool failure) while consuming the stream in runAgentWithOptions.","commonSituations":"Max cost/token budget exhausted mid-run; circuit breaker opened; provider API failure; sandboxed tool crash. The receipt on cause lets you see spend up to the failure.","solutions":["Read error.code for the category and error.cause (receipt) for spend details.","Handle budget-exhaustion codes by raising maxCostUsd/budget or trimming the task.","Retry transient provider/network codes with backoff.","Log event.code + event.message to identify the underlying failing component."],"exampleFix":"// before\nconst result = await run(agent, input); // unhandled CavemanRunError\n// after\ntry {\n  const result = await run(agent, input);\n} catch (e) {\n  if (e instanceof CavemanRunError) console.error(e.code, e.cause?.receipt);\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// pre-check budget before run\nif (budget?.maxUsd !== undefined && estimatedCost > budget.maxUsd) {\n  throw new Error(\"estimated cost exceeds budget\");\n}","typeGuard":"const isCavemanRunError = (e: unknown): e is CavemanRunError =>\n  e instanceof CavemanRunError;","tryCatchPattern":"try {\n  const result = await runAgent(definition, input);\n} catch (e) {\n  if (isCavemanRunError(e)) {\n    console.error(`run failed [${e.code}]: ${e.message}`, e.cause?.receipt);\n  } else throw e;\n}","preventionTips":["Set realistic budgets/maxCostUsd to avoid mid-run exhaustion.","Inspect e.code/e.cause receipt to classify failures before retrying.","Apply backoff retries only for transient provider/network codes.","Monitor breaker state to anticipate run_error from open breakers."],"tags":["run","error-wrapper","budget","provider"],"backgroundTag":"api-error-response","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}