feat(mcp): semantic revert decoding and actionable agent remediation

[GreatSage-dev]

What this changes

Adds semantic EVM revert decoding, Solidity panic translation, and structured, plain-English remediation guidance to KeeperHub's simulation engine and Model Context Protocol (MCP) dry-run diagnostics.

When an autonomous AI agent or execution script simulates a transaction that reverts (e.g. ERC-20 allowance shortfall, contract pause gate, AccessControl permission rejection, or arithmetic division by zero), KeeperHub previously surfaced cryptic revert strings or unparsed hexadecimal data requiring downstream clients to guess the failure root cause.

This PR upgrades simulation preflight errors across execute_transfer, execute_contract_call, and execute_check_and_execute:

1. Solidity Panic Decoding: Adds full classification of standard EVM Panic codes (0x01 Assert, 0x11 Overflow/Underflow, 0x12 DivisionByZero, 0x22 NegativeExponent, 0x31 PopEmptyArray, 0x32 OutOfBounds, 0x41 OutOfMemory).
2. Machine-Readable Codes: Emits typed SimulateFailureCode literals:
   • insufficient_allowance (with structured allowance, neededAllowance, spender)
   • insufficient_token_balance
   • contract_paused
   • unauthorized
   • reentrancy_blocked
   • safe_signature_invalid
   • panic_* (e.g. panic_divisionbyzero, panic_arithmeticoverflowunderflow)
3. Legacy String-Revert Pattern Recognition: Automatically attributes classic ERC-20 / OpenZeppelin string reverts ("ERC20: transfer amount exceeds balance", "ERC20: insufficient allowance", "Pausable: paused", "Ownable: caller is not the owner") to structured codes and remediation.
4. Cognitive Agent Remediation: Attaches actionable, natural language remediation text (e.g., "Call approve() on token contract 0x... with spender 0x... for at least 1000000000000000000 units before retrying this transaction.") directly in the HTTP 400 simulation envelope and MCP tool error hints, with 500-char non-truncating bounds and control-character injection protection.

Zero breaking changes: HTTP response codes (400 Bad Request), status headers, and existing fields (wouldRevert, revertReason, failureKind) remain 100% intact.

Scope

One cohesive, tightly-scoped change: widening KeeperHub's preflight failure classification and threading actionable remediation through failureFromPreflightError(), simulationFailureFromError(), and buildSimulationFailureHint(). All parts are strictly interdependent.

How it was verified

Added and expanded 2 Vitest unit test suites covering the new classification, panic lookup, string-revert matching, remediation generators, untrusted input protection, and MCP tool formatting:

npx vitest run tests/unit/decode-revert-error.test.ts
npx vitest run tests/unit/mcp-simulate-revert-diagnostics.test.ts

[github-actions]

About the build check on this pull request

This pull request comes from a fork, so GitHub does not pass it the credentials build normally uses for our image registry cache and staging build configuration. The build still runs and still compiles the image, so a red build here is real; it just takes longer than on team branches.

Every workflow run on a pull request from a fork also waits for a maintainer to approve it, so checks can sit at "awaiting approval" for a while after each push. Nothing is needed from you for either of these.

[github-actions]

This pull request needs an issue or ticket reference

No issue or ticket reference was found in the title, description, or branch name.

Outside contributions start with an issue. Open one, wait for a maintainer to apply the accepted label, then put #N in the title, for example fix: #1978 return 403 with a body on public /api/chains. No issue is needed for typos, broken links, formatting, or docs corrected to match existing behaviour; retitle with one of: docs chore style release. Full policy: ISSUES.md.

This check reruns on every push and edit, and again on its own once a referenced issue is labelled accepted.