feat(mcp): explain upload failures, attach explanations to failed tasks - #28
Merged
Conversation
Compile failures had beginner-friendly explanations; upload failures - which are MORE confusing because they are about hardware, ports and bootloaders - returned raw esptool/avrdude text. Worse, extractErrors only kept lines containing 'error:', which esptool never prints, so a failed upload reported zero errors; and the explainError fallback hardcoded "Compilation error occurred" even for flashing failures. - Patterns move to module-level tables keyed by tool. The upload table covers the failures a real board actually produces: esptool no-serial-data (native USB vs UART-bridge port + BOOT-button guidance), wrong boot mode, chip/FQBN mismatch, port busy-or-missing, Linux dialout permissions, vanished ports (native-USB re-enumeration), avrdude not-in-sync, brownout, mid-transfer timeout, and a generic esptool fallback ordered last. Upload failures also consult the compile table, since an upload can fail in its compile phase. - extractErrors now keeps esptool/avrdude failure lines. - Failed tasks carry result.explained directly - the place agents actually look - via explainTaskFailure, which falls back through structured errors, stderr extraction, and the task error string, so it is never empty. - arduino_build_output format=explained passes lastBuild.tool, and the fallback explanation is tool-aware. Verified on hardware: upload to a nonexistent port and upload to a port held by the serial monitor both returned failed tasks whose explained entries name the real cause and the fix (including "disconnect the serial monitor"); build_output format=explained after a failed upload no longer claims a compilation error. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fourth of the v0.6.0 series (pain point 4: upload errors got raw esptool text while compile errors got explanations).
What changed
dialout, vanished ports (native-USB re-enumeration), avrdude not-in-sync, brownout, mid-transfer timeout, generic esptool fallback last. Upload failures also consult the compile table (an upload can fail in its compile phase).extractErrorskeeps esptool/avrdude lines — previously a failed upload reported zero errors because esptool never printserror:.result.explaineddirectly — where agents actually look, no follow-up call needed. Never empty (falls back through structured errors → stderr → the task error string).Verified on hardware (ESP32-S3)
explainednames the busy-or-missing cause honestly (esptool's own message is ambiguous between the two)arduino_serial disconnectarduino_build_output format=explainedafter a failed upload no longer claims a compilation error🤖 Generated with Claude Code
EOF