epjUdZddlmZddlZddlmZmZdZdd Zdd Z dd Z ddZ ddZ ddZ ddZee e e e e egZded<ddddZded<ddZdS)uOutput-pattern failure hints for the terminal tool. When a command exits non-zero, the raw stderr often confuses models into wasted diagnostic turns (e.g. retrying `python` when only `python3` exists, or re-sending a gh field list that the installed gh doesn't support). This module extends the exit-code semantics table in ``terminal_tool`` with an *output-pattern* tier: a bounded scan of the command output that maps well-known failure shapes to one short, actionable recovery hint. Design rules (keep these when adding patterns): * Only fires on non-zero exit codes — never annotate success. * At most ONE hint per result, first match wins; patterns are ordered by observed frequency in production trajectories (state.db mining, Aug 2026). * Scans only the first ``_SCAN_CHARS`` of output — hints must key on error headers, not deep context. * Hints state the *next action*, not a diagnosis essay. One or two sentences. * Pure function, no I/O, no config reads — trivially unit-testable. Frequencies quoted below come from a 250k-terminal-result window of the production session DB (Aug 2026): together these classes cover ~14k failed calls whose retry chains averaged 1.4 extra tool turns each. ) annotationsN)CallableOptionalicommandstroutputreturn Optional[str]cftjd|}|sdSd|ddS)NzUnknown JSON field: "?(\w+)z2The installed gh does not support the JSON field 'ub'. The valid field list is printed in the output above — retry using only fields from that list.researchgrouprrms :/home/thesage/.hermes/hermes-agent/tools/terminal_hints.py_hint_gh_unknown_json_fieldr#sH 0&99A t &QWWQZZ & & &ctjd|}|sdS|d}|dkr dS|dkr dSd|d|d S) NzE(?:bash: line \d+: |bash: |sh: \d*:? ?)?([\w.+-]+): command not foundr pythonunThis system has no bare `python` — use `python3`, or the project venv's interpreter (e.g. .venv/bin/python).pipuoThis system has no bare `pip` — use `pip3`, `python3 -m pip`, or the project venv's pip (e.g. .venv/bin/pip).`z6` is not installed or not on PATH. Verify with `which zK`; install it or use an absolute path instead of retrying the same command.r )rrrmissings r_hint_command_not_foundr0s Z\bccA tggajjG( B  % >   %G % % % % %rcftjd|}|sdSd|ddS)Nz?(?:ModuleNotFoundError|ImportError): No module named '?([\w.]+)zPython cannot import 'r z'. Most often the wrong interpreter is running: activate the project venv (e.g. `source .venv/bin/activate`) or invoke its python directly. Only pip install if the package is genuinely absent from that venv.r rs r_hint_module_not_foundrGsK TV\]]A t E E E ErcLtjd|tjsdS dS)Nz-^CONFLICT |Automatic merge failed|needs mergeuGit merge conflict. Do not retry this command. Resolve the conflicted files listed above (edit, then `git add`), then continue (`git rebase --continue` / commit the merge) — or abort with `--abort`.)rrMrrs r_hint_merge_conflictr!Ts/ 9Evrt T Tt rcftjd|}|sdSd|ddS)Nz+(?:fatal|error):.*?'([^']+)' already exists'r u' already exists — retrying unchanged will keep failing. Reuse it, choose another name, or delete it first if it is genuinely stale.r rs r_hint_already_existsr$`sF @&IIA t AGGAJJ   rcd|vrd|vrdS dS)NzAPI rate limitzwas submitted too quicklyu{GitHub API rate limit hit — immediate retries will keep failing. Continue with other work and retry this operation later.r s r_hint_gh_rate_limitr'ls-v%%*EV*S*St Crcd|vrd|vrdS dS)NzPermission deniedEACCESzPermission denied. Check ownership/mode of the target path (`ls -la`); prefer a user-writable location. Only escalate to sudo if the task genuinely requires it.r&r s r_hint_permission_deniedr*vs+&((XV-C-Ct -rz)list[Callable[[str, str], Optional[str]]] _OUTPUT_HINTSu~Exit 126: the file was found but is not executable — `chmod +x` it or invoke it via its interpreter (e.g. `bash script.sh`).uExit 137: the process was SIGKILLed — usually out-of-memory or an external kill. Reduce memory use or check `dmesg | tail` before retrying.zExit 124: the command hit its timeout. Raise timeout= (foreground max 600s) or run it with background=true and notify_on_complete=true.)~|zdict[int, str]_EXIT_CODE_HINTS exit_codeintc|dkrdS|pddt}|r0tD](} ||pd|}n#t$rYwxYw|r|cS)t|S)aReturn one short recovery hint for a failed command, or None. Args: command: The command string that ran. exit_code: Its exit code (non-zero for failures). output: Combined stdout/stderr as returned to the model. Only the first ``_SCAN_CHARS`` characters of output are examined and at most one hint is returned. Returns None for exit_code == 0. rN) _SCAN_CHARSr+ Exceptionr/get)rr0rwindowfnhints rannotate_failurer:sA~~tlL[L )F   B r'-R00           * **s5 AA)rrrrr r )rrr0r1rrr r )__doc__ __future__rrtypingrrr4rrrr!r$r'r*r+__annotations__r/r:r&rrr?s_2#""""" %%%%%%%%     .             <  J Y S$$++++++r