Snapback

Snapback self-heal interceptor for OpenClaw

mcp-name: io.github.ra1labsworkx-wq/snapback

Make Snapback automatic. Instead of remembering to call the diagnosis tool, wrap your agent's tool calls once — and every error is auto-diagnosed, and gated-safe fixes are applied and retried *without a human*.

"Power tools are optional. Infrastructure is not." This turns Snapback from a tool you reach for into

infrastructure that runs on every failure.

Connect the MCP server

Snapback is a hosted remote MCP server — nothing to run locally. Add it to any MCP client (Claude Code, Cursor, Cline, VS Code, Windsurf). Most tools are free and need no token.

{

"mcpServers": { "snapback": { "url": "https://api.snapback.sh/mcp" } } }

Endpoint: https://api.snapback.sh/mcp (Streamable HTTP, JSON-RPC 2.0). Then call tools/list (23 tools) and try diagnose_infra_error with {"error": "dns nxdomain servfail"} → family: dns-tls + a verified fix.

Tools

Free (no token): diagnose_infra_error, detect_loop, budget_guard, search_docs, what_others_did, recommend_failover, cascade_root, suggest_budget_recovery, convert_trace, preflight, session_start, session_step, session_end, discovery.

Metered (free starter token or x402): diagnose_trace, diagnose_batch, get_verdict, submit_feedback, report_outcome, request_pattern, my_usage, my_impact, agent_memory.

• diagnose_infra_error — a cryptic infra error → its family + the verified fix (library-first, ~150ms, no LLM on a hit). 46 families.
• detect_loop — catch a repeating tool-call loop mid-run before the step limit.
• budget_guard — catch token / step / context / cost overruns mid-run.
• what_others_did — anonymized cross-agent outcomes for a failure class.
• diagnose_trace — full multi-step trace diagnosis (metered).

What it does

On any tool-call error, the interceptor:

1. Calls diagnose_infra_error (free, no token, no LLM, <150ms).
2. Applies the three-factor gate — auto-apply a fix only when all are true:

• confidence >= 0.85
• source == "library" (a curated verified fix, not an LLM guess)
• auto_safe == true (the fix is retry / refetch / config — reversible, side-effect-free)

1. If the gate passes → applies the fix and retries once. If it fails → escalates to a human (logs the verdict). It never auto-applies a mutate or destructive fix (create/change state, money, auth grants).

It fails closed: when unsure, it escalates rather than acting.

Install

# no install needed beyond the stdlib; drop the file in, or:

cp snapback_interceptor.py your_agent/ export SNAPBACK_MCP=https://api.snapback.sh/mcp # default; the free tools need no token

Use

from snapback_interceptor import SnapbackInterceptor

heal = SnapbackInterceptor( auto_apply=True, on_escalate=lambda v: my_ops_inbox.log(v), # human sees non-auto-safe verdicts on_heal=lambda v: metrics.count("snapback.autoheal", family=v["family"]), )

wrap any call that might raise:

result = heal.run(call_solana_rpc, wallet, amount)

or as a decorator:

@heal.guard def call_solana_rpc(wallet, amount): ...

or manually on a caught error:

verdict = heal.diagnose("BlockhashNotFound") if verdict"gate": ...apply verdict["fix"] and retry...

The gate contract (returned by Snapback)

diagnose_infra_error returns {matched, family, fix, confidence, source, action_class, auto_safe, gate}. action_class is one of:

Defense in depth (1.8.3): even a reversible-class fix is down-graded to escalate if its text contains a destructive command (delete a pod, flush keys, drop a table). The gate returns gate.contains_destructive_step, so a fix can never auto-run a state-destroying step regardless of its action_class.

gate.auto_apply_ok is the ready-made verdict; the interceptor also re-derives it locally so a stale client can't over-trust.

Privacy & safety

• 100% client-side. Talks only to the free public diagnose_infra_error endpoint.
• Never sends your Snapback token for the diagnosis (diagnosis is free).
• Snapback scrubs trace content server-side; this sends only the error string you pass.
• Composes with bridge.py (post-mortem forwarding) — this is the live auto-heal layer.

Roadmap

• submit_feedback on the retry outcome (did the fix work?) → feeds the shared library (the network effect).
• Hermes + LangChain adapters (same gate, different framework hook).