failecho-autoreport

Automatic failure reporting for agents that are not Claude Code.

Claude Code reports tool failures through a hook that fires after every call, with no model deciding anything. Everywhere else -- LangChain, LlamaIndex, a cron job, a local model driving a scraper -- reporting depends on the model choosing to call a tool, and a small model reliably will not. This removes the decision: wrap the call site once.

from failecho_autoreport import FailEcho

fe = FailEcho()

tools = fe.wrap(tools, service="github-mcp")          # a framework's tool list

@fe.watch(service="api.github.com", operation="create_issue")
def create_issue(title):                              # or one call site
    ...

fe.recovered("api.github.com", "create_issue", "refresh_schema")  # what fixed it

What it sends is a failure's shape: service, operation, a short error class, an HTTP-ish code when there is one, and duration. Never arguments, never return values, never the prompt, never a credential. Error text is off unless FAILECHO_SEND_ERRORS=1.

Three properties it has, each with a test rather than a promise:

• Never raises. A reporting bug cannot become your application's exception.
• Never blocks. Reports go to a worker thread; an unreachable FailEcho costs the caller about 3 ms, not a timeout. (Advice, below, is the opt-in exception.)
• Never changes behaviour. Returns and re-raises exactly what your code did.

Advice for the agent that failed (opt-in)

Reporting helps the next agent. With advise=True (or FAILECHO_ADVISE=1), a failure in a watched call is also followed by one read of the network -- /v1/query, which stores nothing -- and the answer is attached to the exception before it goes on up:

fe = FailEcho(advise=True)

try:
    create_issue("...")
except Exception as exc:
    exc.failecho          # the network's answer, a dict, or None
    fe.advice_text(exc)   # one line, e.g. "FailEcho: try <action>, worked n/m ..."

Put that line in the tool error your model sees and the model has the evidence when it decides whether to retry, without having to think of asking. Nothing is acted on for you; the exception's type and message are unchanged (on Python 3.11+ the line is also added as a note). The read waits at most 3 seconds, on failures only -- the one place this package waits, which is why it is off by default.

The recovered() line is the one worth bothering with. Failures alone give the network a failure rate; only an outcome records what fixed it, which is the half another agent can act on. It cannot be inferred, so it stays one explicit call.

Zero dependencies. FAILECHO_DISABLED=1 turns it off. Point endpoint= at your own server to send nothing to anyone else. The network at failecho.com is public and, as of this release, has no independent reporters yet -- the front page says so. Works on your own history alone from five recoveries.

MIT. Source: https://github.com/FailEcho/failecho