coder-eval 0.8.2__py3-none-any.whl

coder_eval/criteria/skill_triggered.py

@@ -0,0 +1,111 @@
+"""Skill-triggered criterion checker: did the agent engage the target skill?
+
+Agent-agnostic. Claude Code engages a skill via an explicit ``Skill`` tool call;
+Codex has no such tool — it auto-discovers skills under ``.agents/skills/`` and
+engages one by reading its ``SKILL.md`` / references off disk via shell. Both
+signals are detected here so the criterion scores identically across agents.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from coder_eval.criteria._classification_aggregate import overlay_classification_metrics
+from coder_eval.criteria.base import BaseCriterion, register_criterion
+from coder_eval.models import (
+    ClassificationCriterionResult,
+    CriterionAggregate,
+    CriterionResult,
+    SkillTriggeredCriterion,
+)
+
+
+if TYPE_CHECKING:
+    from coder_eval.criteria.base import CheckContext
+    from coder_eval.models.results import TurnRecord
+    from coder_eval.models.telemetry import CommandTelemetry
+    from coder_eval.sandbox import Sandbox
+
+logger = logging.getLogger(__name__)
+
+_YES = "yes"
+_NO = "no"
+
+
+def _engaged_skill(cmd: CommandTelemetry, skill_name: str) -> bool:
+    """True when one command engaged ``skill_name`` — agent-agnostically.
+
+    Claude: an explicit ``Skill`` tool call carries the skill in
+    ``parameters['skill']`` (optionally namespaced, e.g. ``plugin:uipath-agents``).
+
+    Codex (and any non-Claude agent): no ``Skill`` tool exists, so the skill is
+    engaged by reading its files off disk via shell. Both the repo layout
+    (``.../skills/<skill_name>/...``) and the sandbox symlink
+    (``.agents/skills/<skill_name>/...``) contain the substring
+    ``skills/<skill_name>/``, which appears in the recorded command string
+    (Bash ``parameters['command']``) or a file-path parameter. The trailing
+    slash prevents prefix collisions (``uipath-agents`` vs ``uipath-agents-foo``).
+    """
+    if cmd.tool_name == "Skill" and cmd.parameters.get("skill", "").split(":")[-1] == skill_name:
+        return True
+    needle = f"skills/{skill_name}/"
+    return any(isinstance(v, str) and needle in v for v in cmd.parameters.values())
+
+
+@register_criterion
+class SkillTriggeredChecker(BaseCriterion[SkillTriggeredCriterion]):
+    """Binary classifier: observed='yes' when the agent engaged the target skill.
+
+    Returns a ``ClassificationCriterionResult`` so the suite aggregator can
+    compute accuracy / recall / F1 / confusion matrix across all rows.
+    """
+
+    criterion_type = "skill_triggered"
+
+    def _check_impl(
+        self,
+        criterion: SkillTriggeredCriterion,
+        sandbox: Sandbox,
+        reference_code: str | None = None,
+        *,
+        turn_records: list[TurnRecord] | None = None,
+        context: CheckContext | None = None,
+    ) -> CriterionResult:
+        if turn_records is None:
+            return CriterionResult(
+                criterion_type=criterion.type,
+                description=criterion.description,
+                score=0.0,
+                details="No turn records available",
+                error="turn_records not provided to checker",
+            )
+
+        triggered: bool = any(
+            _engaged_skill(cmd, criterion.skill_name) for turn in turn_records for cmd in turn.commands
+        )
+        expected_yes: bool = criterion.expected_skill == criterion.skill_name
+        score = 1.0 if triggered == expected_yes else 0.0
+        observed = _YES if triggered else _NO
+        expected = _YES if expected_yes else _NO
+
+        filt = f" (skill_name={criterion.skill_name!r})"
+        return ClassificationCriterionResult(
+            criterion_type=criterion.type,
+            description=criterion.description,
+            score=score,
+            details=f"observed={observed!r}, expected={expected!r}{filt}",
+            observed_label=observed,
+            expected_label=expected,
+        )
+
+    def aggregate(
+        self,
+        criterion: SkillTriggeredCriterion,
+        per_row_results: list[CriterionResult],
+    ) -> CriterionAggregate | None:
+        """Baseline stats (from super) + classification overlay (accuracy/F1/...)."""
+        base = super().aggregate(criterion, per_row_results)
+        if base is None:
+            return None
+        return overlay_classification_metrics(base, per_row_results)

coder_eval/criteria/uipath_eval.py

@@ -0,0 +1,223 @@
+"""UiPath eval criterion checker."""
+
+import json
+import logging
+import re
+import shlex
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from coder_eval.criteria.base import BaseCriterion, CheckContext, register_criterion
+from coder_eval.models import CriterionResult, UiPathEvalCriterion
+
+
+# Detector for "the `uipath` CLI is not available in the sandbox". Sandboxes run
+# on Linux (/bin/sh — dash on Ubuntu), so exit code 127 + "command not found" is
+# the only shell signal we need to recognize. The regex also matches the python
+# ModuleNotFoundError format for tasks that run `python -m uipath`.
+_UIPATH_MISSING_PATTERN = re.compile(
+    r"\buipath\b.*command not found|no module named ['\"]?uipath['\"]?(?:\s|$)",
+    re.IGNORECASE,
+)
+
+
+if TYPE_CHECKING:
+    from coder_eval.models.results import TurnRecord
+    from coder_eval.sandbox import Sandbox
+
+logger = logging.getLogger(__name__)
+
+
+@register_criterion
+class UiPathEvalChecker(BaseCriterion[UiPathEvalCriterion]):
+    """Checker for UiPathEvalCriterion."""
+
+    criterion_type = "uipath_eval"
+
+    def _check_impl(
+        self,
+        criterion: UiPathEvalCriterion,
+        sandbox: "Sandbox",
+        reference_code: str | None = None,
+        *,
+        turn_records: list["TurnRecord"] | None = None,
+        context: CheckContext | None = None,
+    ) -> CriterionResult:
+        """Check UiPath agent evaluation results against specified thresholds.
+
+        Args:
+            criterion: UiPathEvalCriterion with agent_name, eval_set, and thresholds
+            sandbox: Sandbox instance for file access and command execution
+            reference_code: Not used for this criterion
+            turn_records: Not used for this criterion
+
+        Returns:
+            CriterionResult with score (0.0-1.0) based on threshold compliance
+        """
+        # Resolve eval_set path relative to task directory
+        eval_set_path = criterion.eval_set
+        task_dir = sandbox.task_dir
+        if task_dir:
+            resolved_path = (task_dir / criterion.eval_set).resolve()
+            if resolved_path.exists():
+                eval_set_path = str(resolved_path)
+
+        # Use a unique output filename to avoid conflicts
+        output_filename = f"uipath_eval_output_{uuid.uuid4().hex[:8]}.json"
+
+        # Run the evaluation command with properly escaped arguments
+        cmd = (
+            f"uv run uipath eval {shlex.quote(criterion.agent_name)} "
+            f"{shlex.quote(eval_set_path)} --no-report --output-file {shlex.quote(output_filename)}"
+        )
+        exit_code, _, stderr = sandbox.run_command(cmd)
+
+        if exit_code != 0:
+            stderr_text = stderr or ""
+            # Exit code 127 is the POSIX "command not found" signal; the regex
+            # also catches `ModuleNotFoundError` for tasks that invoke
+            # `python -m uipath` instead of the CLI.
+            cli_missing = exit_code == 127 or bool(_UIPATH_MISSING_PATTERN.search(stderr_text))
+            hint = ""
+            if cli_missing:
+                # The host's `[uipath]` extra installs `uipath` into the host
+                # venv; the sandbox runs in its own `uv` environment and must
+                # resolve `uipath` from the task's own deps.
+                hint = (
+                    " — the sandbox could not resolve the `uipath` CLI. "
+                    "Ensure the task's Python deps include `uipath` (the in-sandbox "
+                    "dependency is separate from the host's `coder-eval[uipath]` extra)."
+                )
+            return CriterionResult(
+                criterion_type=criterion.type,
+                description=criterion.description,
+                score=0.0,
+                details=f"Command failed with exit code {exit_code}: {stderr}{hint}",
+            )
+
+        # Parse the output JSON file
+        try:
+            output_content = sandbox.get_file_content(output_filename)
+            results = json.loads(output_content)
+        except Exception as e:
+            return CriterionResult(
+                criterion_type=criterion.type,
+                description=criterion.description,
+                score=0.0,
+                details=f"Failed to parse {output_filename}: {e}",
+            )
+
+        if not isinstance(results, dict):
+            return CriterionResult(
+                criterion_type=criterion.type,
+                description=criterion.description,
+                score=0.0,
+                details=f"Expected JSON object in {output_filename}, got {type(results).__name__}",
+            )
+
+        # Calculate metrics from evaluation results
+        metrics = self._calculate_metrics(results)
+
+        # Compare metrics against thresholds
+        failed_metrics = []
+        for metric_name, threshold in criterion.thresholds.items():
+            if metric_name not in metrics:
+                failed_metrics.append(f"Missing metric: {metric_name}")
+                continue
+
+            metric_value = metrics[metric_name]
+            if not isinstance(metric_value, (int, float)):
+                failed_metrics.append(f"{metric_name}: Invalid type {type(metric_value).__name__} (expected number)")
+            elif metric_value < threshold:
+                failed_metrics.append(f"{metric_name}: {metric_value} < {threshold}")
+
+        # Calculate score based on how many thresholds are met
+        if not criterion.thresholds:
+            score = 1.0
+        else:
+            metrics_passed = len(criterion.thresholds) - len(failed_metrics)
+            score = metrics_passed / len(criterion.thresholds)
+
+        details = "All thresholds met." if not failed_metrics else f"Failed metrics: {', '.join(failed_metrics)}"
+
+        return CriterionResult(
+            criterion_type=criterion.type,
+            description=criterion.description,
+            score=score,
+            details=details,
+        )
+
+    def _calculate_metrics(self, results: Any) -> dict[str, float]:
+        """Calculate aggregated metrics from evaluation results.
+
+        Supports two formats:
+        1. Complex format with evaluationSetResults (from UiPath agents)
+        2. Simple format with flat metric keys (for testing/direct evaluation)
+
+        Args:
+            results: Parsed output.json with either evaluationSetResults or flat metrics
+
+        Returns:
+            Dictionary with calculated metrics
+        """
+        # Try complex format first (evaluationSetResults)
+        evaluation_set_results = results.get("evaluationSetResults", [])
+        if evaluation_set_results:
+            return self._calculate_metrics_from_evaluations(evaluation_set_results)
+
+        # Fall back to simple format (flat metrics)
+        # Keep all values including non-numeric ones, to catch type errors later
+        metrics = dict(results)
+
+        logger.debug(f"Calculated metrics: {metrics}")
+        return metrics
+
+    def _calculate_metrics_from_evaluations(self, evaluation_set_results: Any) -> dict[str, float]:
+        """Calculate metrics from evaluationSetResults structure.
+
+        Groups metrics by evaluator ID, averages scores per evaluator (treating
+        exceptions as 0.0), then computes macro average across all evaluators.
+
+        Args:
+            evaluation_set_results: List of evaluation results with evaluatorId
+
+        Returns:
+            Dictionary with calculated metrics, keyed by evaluator ID or "*" for macro average
+        """
+        evaluator_scores: dict[str, list[float]] = {}  # evaluator_id -> list of scores
+
+        # Iterate through all evaluations and collect scores by evaluator
+        for evaluation in evaluation_set_results:
+            evaluation_run_results = evaluation.get("evaluationRunResults", [])
+            for run_result in evaluation_run_results:
+                evaluator_id = run_result.get("evaluatorId")
+                if not evaluator_id:
+                    continue
+
+                result_data = run_result.get("result", {})
+                score = result_data.get("score", 0.0)
+
+                # Treat missing/error/non-numeric scores as 0.0
+                if not isinstance(score, (int, float)):
+                    score = 0.0
+
+                if evaluator_id not in evaluator_scores:
+                    evaluator_scores[evaluator_id] = []
+                evaluator_scores[evaluator_id].append(score)
+
+        # Calculate per-evaluator averages
+        metrics = {}
+        evaluator_averages = []
+        for evaluator_id, scores in evaluator_scores.items():
+            avg_score = sum(scores) / len(scores) if scores else 0.0
+            metrics[evaluator_id] = avg_score
+            evaluator_averages.append(avg_score)
+
+        # Calculate macro average (average of evaluator averages)
+        if evaluator_averages:
+            metrics["*"] = sum(evaluator_averages) / len(evaluator_averages)
+        else:
+            metrics["*"] = 0.0
+
+        logger.debug(f"Calculated metrics: {metrics}")
+        return metrics

coder_eval/errors/__init__.py

@@ -0,0 +1,26 @@
+"""Error categorization, retry logic, and error context capture.
+
+This package provides production-grade error handling with:
+- A categorized error taxonomy with per-category retry eligibility
+- Exponential backoff retry logic with jitter
+- Rich error context capture for debugging
+- Actionable error tips for users
+"""
+
+from .agent import AgentConfigError, AgentCrashError, format_timeout_reason, truncate_crash_message
+from .budget import BudgetExceededError
+from .judge import JudgeInfrastructureError
+from .timeout import EvaluationTimeoutError, TaskTimeoutError, TurnTimeoutError
+
+
+__all__ = [
+    "AgentConfigError",
+    "AgentCrashError",
+    "BudgetExceededError",
+    "EvaluationTimeoutError",
+    "JudgeInfrastructureError",
+    "TaskTimeoutError",
+    "TurnTimeoutError",
+    "format_timeout_reason",
+    "truncate_crash_message",
+]

coder_eval/errors/agent.py

@@ -0,0 +1,26 @@
+"""Agent-specific exceptions and crash-reason formatting helpers."""
+
+CRASH_REASON_MAX_CHARS = 200
+
+
+def format_timeout_reason(timeout_seconds: float) -> str:
+    """Canonical ``crash_reason`` string for an agent-turn timeout (integer seconds)."""
+    return f"Agent turn timed out after {timeout_seconds:.0f}s"
+
+
+def truncate_crash_message(message: str, *, limit: int = CRASH_REASON_MAX_CHARS) -> str:
+    """Cap a crash-reason string with a single Unicode ellipsis on overflow."""
+    return message if len(message) <= limit else message[:limit] + "…"
+
+
+class AgentCrashError(RuntimeError):
+    """Mid-turn agent failure; routed to AGENT_CRASH by isinstance."""
+
+
+class AgentConfigError(RuntimeError):
+    """Agent prerequisite missing (env var, SDK path, build artifact). Non-retryable.
+
+    Routed to ``AGENT_CONFIG_ERROR`` by isinstance — preferred over substring
+    matching on a message, which can silently re-categorise a reworded
+    RuntimeError as the retryable ``AGENT_API_ERROR``.
+    """

coder_eval/errors/budget.py

@@ -0,0 +1,28 @@
+"""Budget-exceeded exceptions for evaluation lifecycle."""
+
+from __future__ import annotations
+
+
+class BudgetExceededError(Exception):
+    """Raised when a RunLimits budget is exceeded between agent turns.
+
+    Carries which budget tripped and the over-budget value so the
+    orchestrator can record the status reason without re-computing.
+    """
+
+    def __init__(
+        self,
+        budget_name: str,
+        *,
+        actual: float,
+        limit: float,
+        task_id: str | None = None,
+        iteration: int | None = None,
+    ):
+        self.budget_name = budget_name
+        self.actual = actual
+        self.limit = limit
+        self.task_id = task_id
+        self.iteration = iteration
+        suffix = f" (iteration {iteration})" if iteration is not None else ""
+        super().__init__(f"{budget_name} budget exceeded: {actual:g} > {limit:g}{suffix}")

coder_eval/errors/categories.py

@@ -0,0 +1,205 @@
+"""Error categories and configuration for retry logic.
+
+This module defines error categories, retry configuration, and structured
+error context for production-grade error handling.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ErrorCategory(Enum):
+    """Categorize errors for retry logic and reporting.
+
+    Categories are grouped by component:
+    - Agent errors (AGENT_*)
+    - Sandbox errors (SANDBOX_*, VENV_*, PACKAGE_*, etc.)
+    - Evaluator errors (CRITERION_*, LLM_REVIEWER_*)
+    - Task errors (TASK_*)
+    - System errors (DISK_FULL, OUT_OF_MEMORY)
+
+    Each category has an associated retry policy in RETRY_CONFIG.
+
+    NB: each ``value`` is persisted verbatim into task.json's
+    ``error_details.error_category`` — a cross-repo contract surface read by the
+    external eval-runner/dashboard. Adding/renaming/removing a member is a
+    contract change: update the pinned set in
+    ``tests/test_error_handling.py::test_error_category_values_are_a_pinned_contract``
+    and flag in the PR that a new persisted value now appears downstream (which
+    needs a display label/icon). FinalStatus bucketing is unchanged, so the
+    blast radius is display/filter only.
+
+    Removed 2026-06-22: ``TESTS_FAILED`` and ``SANDBOX_COMMAND_ERROR`` — neither
+    had a producing ``categorize_error`` path or a downstream consumer. The
+    liveness test in ``tests/test_error_handling.py`` now keeps every member
+    producible, so a future dead member fails CI.
+    """
+
+    # Agent Errors - Communication and execution errors
+    AGENT_TIMEOUT = "agent_timeout"  # Agent exceeded time limit (NOT retryable)
+    AGENT_API_ERROR = "agent_api_error"  # API connection/network error (retryable)
+    AGENT_RATE_LIMIT = "agent_rate_limit"  # API rate limit (retryable with long delay)
+    AGENT_AUTH_ERROR = "agent_auth_error"  # Invalid API key (NOT retryable)
+    AGENT_BILLING_ERROR = "agent_billing_error"  # Insufficient credits/billing issue (NOT retryable)
+    AGENT_CRASH = "agent_crash"  # Agent process crashed (retryable — CLI crashes are often transient)
+    AGENT_INVALID_OUTPUT = "agent_invalid_output"  # Malformed response (NOT retryable)
+    AGENT_CONFIG_ERROR = "agent_config_error"  # Missing prerequisite/misconfiguration (NOT retryable)
+
+    # Sandbox Errors - Environment setup and execution
+    SANDBOX_SETUP_ERROR = "sandbox_setup_error"  # Failed to create sandbox (retryable)
+    VENV_CREATION_ERROR = "venv_creation_error"  # Virtual env creation failed (retryable)
+    PACKAGE_INSTALL_ERROR = "package_install_error"  # pip install failed (retryable)
+    TEMPLATE_COPY_ERROR = "template_copy_error"  # Template copy failed (retryable)
+    GIT_CLONE_ERROR = "git_clone_error"  # Git clone failed (retryable)
+
+    # Criterion/Evaluator Errors
+    CRITERION_CHECK_ERROR = "criterion_check_error"  # Error checking criterion (NOT retryable)
+
+    # Task Errors - Task definition and loading
+    TASK_NOT_FOUND = "task_not_found"  # Task file doesn't exist (NOT retryable)
+    TASK_INVALID = "task_invalid"  # Malformed task.yaml (NOT retryable)
+
+    # System Errors - Resource exhaustion
+    DISK_FULL = "disk_full"  # No disk space (NOT retryable)
+    OUT_OF_MEMORY = "out_of_memory"  # OOM error (NOT retryable)
+
+    # Budget governance — RunLimits caps tripped (NOT retryable — retrying compounds the breach)
+    BUDGET_EXCEEDED = "budget_exceeded"
+
+    # Unknown
+    UNKNOWN = "unknown"  # Uncategorized error (NOT retryable)
+
+
+class RetryConfig(BaseModel):
+    """Configuration for retry behavior.
+
+    Defines how many times to retry and with what backoff strategy.
+    """
+
+    max_retries: int = Field(default=0, ge=0, description="Maximum retry attempts (0 = no retry)")
+    backoff_multiplier: float = Field(default=2.0, gt=0, description="Exponential backoff multiplier")
+    initial_delay: float = Field(default=5.0, gt=0, description="Initial delay in seconds")
+
+
+class ErrorContext(BaseModel):
+    """Structured error context for reporting and debugging.
+
+    This model provides type-safe error context with validation.
+    Use error_context_to_dict() to convert to dict for EvaluationResult.error_details.
+    """
+
+    error_category: str = Field(description="Error category value")
+    error_message: str = Field(description="Exception message")
+    stack_trace: str = Field(description="Full stack trace")
+    task_id: str = Field(description="Task identifier")
+    component: str | None = Field(default=None, description="Component that failed")
+    agent_name: str | None = Field(default=None, description="Agent name if applicable")
+    attempt_number: int = Field(ge=1, description="Attempt number (1-indexed)")
+    is_retryable: bool = Field(description="Whether error is retryable")
+    retry_delay_seconds: float = Field(ge=0.0, description="Delay before next retry")
+    disk_usage_gb: float | None = Field(default=None, description="Disk usage in GB")
+    memory_usage_gb: float | None = Field(default=None, description="Memory usage in GB")
+    agent_stdout: str | None = Field(default=None, description="Agent stdout (truncated)")
+    agent_stderr: str | None = Field(default=None, description="Agent stderr (truncated)")
+    timestamp: str = Field(description="ISO timestamp when error occurred")
+
+
+# Retry configuration per error category
+# Non-retryable errors have max_retries=0 (default)
+RETRY_CONFIG: dict[ErrorCategory, RetryConfig] = {
+    # Agent errors - API issues are retryable
+    ErrorCategory.AGENT_API_ERROR: RetryConfig(
+        max_retries=3,
+        backoff_multiplier=2.0,
+        initial_delay=5.0,
+    ),
+    ErrorCategory.AGENT_RATE_LIMIT: RetryConfig(
+        max_retries=5,
+        backoff_multiplier=3.0,
+        initial_delay=60.0,  # 1 minute initial delay
+    ),
+    ErrorCategory.AGENT_CRASH: RetryConfig(
+        max_retries=2,
+        backoff_multiplier=2.0,
+        initial_delay=5.0,
+    ),
+    # Sandbox errors - transient failures are retryable
+    ErrorCategory.SANDBOX_SETUP_ERROR: RetryConfig(
+        max_retries=2,
+        backoff_multiplier=1.5,
+        initial_delay=10.0,
+    ),
+    ErrorCategory.PACKAGE_INSTALL_ERROR: RetryConfig(
+        max_retries=2,
+        backoff_multiplier=2.0,
+        initial_delay=5.0,
+    ),
+    ErrorCategory.VENV_CREATION_ERROR: RetryConfig(
+        max_retries=2,
+        backoff_multiplier=2.0,
+        initial_delay=5.0,
+    ),
+    ErrorCategory.TEMPLATE_COPY_ERROR: RetryConfig(
+        max_retries=2,
+        backoff_multiplier=1.5,
+        initial_delay=5.0,
+    ),
+    ErrorCategory.GIT_CLONE_ERROR: RetryConfig(
+        max_retries=3,
+        backoff_multiplier=2.0,
+        initial_delay=10.0,
+    ),
+    # All other errors are NOT retryable (max_retries=0 by default)
+}
+
+
+# Error tip system for better UX
+ERROR_TIPS = {
+    ErrorCategory.AGENT_TIMEOUT: (
+        "Agent or task timed out. Consider increasing the limit "
+        "(-D run_limits.turn_timeout=… or -D run_limits.task_timeout=…), "
+        "or simplifying the task to require fewer iterations."
+    ),
+    ErrorCategory.AGENT_RATE_LIMIT: (
+        "Rate limit hit. Consider using --max-parallel=1 to reduce concurrent API calls, "
+        "or check your API key quota at your provider's dashboard."
+    ),
+    ErrorCategory.AGENT_AUTH_ERROR: (
+        "Authentication failed. Verify your ANTHROPIC_API_KEY is set correctly in .env file and has not expired."
+    ),
+    ErrorCategory.PACKAGE_INSTALL_ERROR: (
+        "Package installation failed. Check your network connection, or try clearing pip cache with 'pip cache purge'."
+    ),
+    ErrorCategory.DISK_FULL: (
+        "Disk full. Run 'coder-eval health' to check usage, then 'coder-eval gc' to free space, "
+        "or delete old runs manually from the runs/ directory."
+    ),
+    ErrorCategory.VENV_CREATION_ERROR: (
+        "Virtual environment creation failed. Ensure Python 3.13+ is installed and accessible."
+    ),
+    ErrorCategory.GIT_CLONE_ERROR: (
+        "Git clone failed. Check your network connection and verify the repository URL is accessible."
+    ),
+    ErrorCategory.AGENT_API_ERROR: (
+        "API connection error. Check your network connection and verify the API endpoint is accessible."
+    ),
+    ErrorCategory.AGENT_BILLING_ERROR: (
+        "Insufficient API credits or billing issue. Check your account balance and billing settings "
+        "at your provider's dashboard."
+    ),
+    ErrorCategory.AGENT_CRASH: (
+        "Claude CLI process exited unexpectedly. Common causes: insufficient API credits, "
+        "invalid API key, or network issues. Run 'claude --version' to verify the CLI works, "
+        "then try running your prompt directly with 'claude' to see the actual error."
+    ),
+    ErrorCategory.BUDGET_EXCEEDED: (
+        "RunLimits budget exceeded. Raise the cap in the task's run_limits block, or simplify "
+        "the prompt to use fewer tokens."
+    ),
+    ErrorCategory.AGENT_CONFIG_ERROR: (
+        "Agent configuration error — a required environment variable, SDK path, or "
+        "build artifact is missing. Check the error message for the specific prerequisite, "
+        "and see the agent plugin's setup docs."
+    ),
+}