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.

Private mode: your team's evidence only

Set FAILECHO_TEAM (or FailEcho(team_token=...)) to a secret your team shares -- 16 characters at least, 32 random bytes is right. Every report is then stored for your team alone: never pooled, never public, never counted. A failure's advice comes from your team's own history when the public network has none, labelled as yours:

FailEcho (your team's own history): try wait_and_retry, worked 5/5.

and it says skip when five of your recent attempts all failed. There is no account: the token is the team, so treat it like a password. DELETE /v1/team removes everything stored under it; POST /v1/team/rotate moves it to a new token if it leaks. Free while the network is bootstrapping.

Signed reports (optional)

python -m failecho_autoreport identity creates an Ed25519 key on this machine and prints its id; FAILECHO_SIGN=1 signs every report with it, so nobody else can report under your reporter id. It proves the key, not a person -- keys are free to make -- and it replaces this installation's reporter id with the key's, so its history starts over. Off by default.

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