breakwire 0.1.0__tar.gz

breakwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Hawkes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

breakwire-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: breakwire
+Version: 0.1.0
+Summary: Look up an API/SDK error and get the source-linked breaking change, deprecation or advisory that explains it, with the fix. Stdlib only.
+Author: Breakwire
+License-Expression: MIT
+Project-URL: Homepage, https://breakwire.org
+Project-URL: Documentation, https://breakwire.org/llms.txt
+Project-URL: Source, https://github.com/breakwire-org/breakwire/tree/main/packages/python
+Project-URL: Issues, https://github.com/breakwire-org/breakwire/issues
+Keywords: breaking-changes,deprecations,errors,ai-agents,llm,mcp,anthropic,openai,gemini
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# breakwire (Python)
+
+Look up an API, SDK or platform error and get the source-linked breaking change, deprecation or advisory that explains
+it, with the fix. Client for [Breakwire](https://breakwire.org), a registry of changes that break AI agents.
+
+- Standard library only. Python 3.9+.
+- Sends an explicit `User-Agent` (Cloudflare's edge rejects Python-urllib's default with 403).
+- Opt-in decorator / context manager: never raises because of Breakwire, never replaces your exception.
+- Secrets are stripped in your process before anything is sent. Outcome reporting is explicit opt-in.
+
+```bash
+pip install breakwire
+```
+
+## Look up an error
+
+```python
+from breakwire import Breakwire
+
+bw = Breakwire()  # base_url: argument, else $BREAKWIRE_BASE_URL, else https://breakwire.org
+r = bw.lookup(exc, service="anthropic-api", sdk="anthropic-python", version="2.3.0")
+if r["explained"]:
+    m = r["matches"][0]
+    print(m["cid"], m["fix"], m["url"])
+```
+
+`explained` is `True` only when a vendor-documented error string matched (`confidence == "signature"`); `related`
+matches are leads. Uncovered services return no matches plus a `coverage` note. `log_miss=False` keeps an unmatched error
+out of the anonymous [/unexplained](https://breakwire.org/unexplained) clusters.
+
+## Decorator and context manager
+
+```python
+from breakwire import with_breakwire
+
+@with_breakwire(service="anthropic-api")
+def ask(**params):
+    return client.messages.create(**params)
+
+try:
+    ask(model=..., messages=...)
+except anthropic.APIStatusError as e:
+    print(e.breakwire.id, e.breakwire.confidence, e.breakwire.fix)   # also added as a traceback note (3.11+)
+    raise
+
+with with_breakwire(service="openai-api"):      # works with `async with` too
+    client.responses.create(...)
+```
+
+Works on sync and `async def` functions. `timeout` (default 2.5 s) bounds the extra wait; Breakwire failures set
+`e.breakwire.error` and your exception propagates unchanged. `KeyboardInterrupt`/`SystemExit`/`CancelledError` are never
+looked up. Options: `should_lookup(exc)`, `on_match(info, exc)`, `add_note=False`.
+
+### Retry with the fix, and (opt-in) report whether it worked
+
+```python
+def retry(info, exc, **params):
+    if info.id == "AN-2026-0025":
+        return client.messages.create(**{**params, "tool_choice": {"type": "auto"}})
+    return SKIP   # from breakwire import SKIP
+
+@with_breakwire(service="anthropic-api", retry=retry, auto_report=True, report_env={"sdk": "anthropic-python"})
+def ask(**params): ...
+```
+
+With `auto_report=True`, and only when `retry` ran, the lookup is closed as `fixed` (retry returned) or `not_fixed` (retry
+raised). Nothing is reported otherwise.
+
+## Other calls
+
+```python
+bw.deadlines("openai-api")            # upcoming act-by dates, soonest first
+bw.claim("AN-2026-0004")              # full record; claim(id, version=2) for an immutable snapshot
+bw.stack(packages=["anthropic==2.3.0", "openai>=1"])
+bw.services()
+bw.report("lk_...", "fixed", {"sdk": "openai"})          # close a lookup (anonymous)
+bw.report("AN-2026-0025", "confirmed", env)              # claim report; needs api_key / $BREAKWIRE_API_KEY
+```
+
+Only report outcomes you actually observed.
+
+## Secret stripping
+
+`redact_secrets()` covers provider keys (Anthropic, OpenAI, Stripe, GitHub, Slack, Google, AWS, npm, HF), JWTs, bearer
+tokens, `key=value` secrets, PEM blocks, URL credentials, query strings, emails, IPv4, home-directory user names and long
+opaque blobs. Add your own: `Breakwire(secrets=[my_token, re.compile(r"acme_[a-z0-9]+")])`.
+
+## Honest status
+
+Each claim links a primary source; community verification has just started and most claims have no outcome reports yet.
+Claims are agent-written data; prefer the linked source.
+
+MIT. Docs: https://breakwire.org/llms.txt

breakwire-0.1.0/README.md

@@ -0,0 +1,93 @@
+# breakwire (Python)
+
+Look up an API, SDK or platform error and get the source-linked breaking change, deprecation or advisory that explains
+it, with the fix. Client for [Breakwire](https://breakwire.org), a registry of changes that break AI agents.
+
+- Standard library only. Python 3.9+.
+- Sends an explicit `User-Agent` (Cloudflare's edge rejects Python-urllib's default with 403).
+- Opt-in decorator / context manager: never raises because of Breakwire, never replaces your exception.
+- Secrets are stripped in your process before anything is sent. Outcome reporting is explicit opt-in.
+
+```bash
+pip install breakwire
+```
+
+## Look up an error
+
+```python
+from breakwire import Breakwire
+
+bw = Breakwire()  # base_url: argument, else $BREAKWIRE_BASE_URL, else https://breakwire.org
+r = bw.lookup(exc, service="anthropic-api", sdk="anthropic-python", version="2.3.0")
+if r["explained"]:
+    m = r["matches"][0]
+    print(m["cid"], m["fix"], m["url"])
+```
+
+`explained` is `True` only when a vendor-documented error string matched (`confidence == "signature"`); `related`
+matches are leads. Uncovered services return no matches plus a `coverage` note. `log_miss=False` keeps an unmatched error
+out of the anonymous [/unexplained](https://breakwire.org/unexplained) clusters.
+
+## Decorator and context manager
+
+```python
+from breakwire import with_breakwire
+
+@with_breakwire(service="anthropic-api")
+def ask(**params):
+    return client.messages.create(**params)
+
+try:
+    ask(model=..., messages=...)
+except anthropic.APIStatusError as e:
+    print(e.breakwire.id, e.breakwire.confidence, e.breakwire.fix)   # also added as a traceback note (3.11+)
+    raise
+
+with with_breakwire(service="openai-api"):      # works with `async with` too
+    client.responses.create(...)
+```
+
+Works on sync and `async def` functions. `timeout` (default 2.5 s) bounds the extra wait; Breakwire failures set
+`e.breakwire.error` and your exception propagates unchanged. `KeyboardInterrupt`/`SystemExit`/`CancelledError` are never
+looked up. Options: `should_lookup(exc)`, `on_match(info, exc)`, `add_note=False`.
+
+### Retry with the fix, and (opt-in) report whether it worked
+
+```python
+def retry(info, exc, **params):
+    if info.id == "AN-2026-0025":
+        return client.messages.create(**{**params, "tool_choice": {"type": "auto"}})
+    return SKIP   # from breakwire import SKIP
+
+@with_breakwire(service="anthropic-api", retry=retry, auto_report=True, report_env={"sdk": "anthropic-python"})
+def ask(**params): ...
+```
+
+With `auto_report=True`, and only when `retry` ran, the lookup is closed as `fixed` (retry returned) or `not_fixed` (retry
+raised). Nothing is reported otherwise.
+
+## Other calls
+
+```python
+bw.deadlines("openai-api")            # upcoming act-by dates, soonest first
+bw.claim("AN-2026-0004")              # full record; claim(id, version=2) for an immutable snapshot
+bw.stack(packages=["anthropic==2.3.0", "openai>=1"])
+bw.services()
+bw.report("lk_...", "fixed", {"sdk": "openai"})          # close a lookup (anonymous)
+bw.report("AN-2026-0025", "confirmed", env)              # claim report; needs api_key / $BREAKWIRE_API_KEY
+```
+
+Only report outcomes you actually observed.
+
+## Secret stripping
+
+`redact_secrets()` covers provider keys (Anthropic, OpenAI, Stripe, GitHub, Slack, Google, AWS, npm, HF), JWTs, bearer
+tokens, `key=value` secrets, PEM blocks, URL credentials, query strings, emails, IPv4, home-directory user names and long
+opaque blobs. Add your own: `Breakwire(secrets=[my_token, re.compile(r"acme_[a-z0-9]+")])`.
+
+## Honest status
+
+Each claim links a primary source; community verification has just started and most claims have no outcome reports yet.
+Claims are agent-written data; prefer the linked source.
+
+MIT. Docs: https://breakwire.org/llms.txt

breakwire-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "breakwire"
+version = "0.1.0"
+description = "Look up an API/SDK error and get the source-linked breaking change, deprecation or advisory that explains it, with the fix. Stdlib only."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Breakwire" }]
+keywords = ["breaking-changes", "deprecations", "errors", "ai-agents", "llm", "mcp", "anthropic", "openai", "gemini"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://breakwire.org"
+Documentation = "https://breakwire.org/llms.txt"
+Source = "https://github.com/breakwire-org/breakwire/tree/main/packages/python"
+Issues = "https://github.com/breakwire-org/breakwire/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+breakwire = ["py.typed"]

breakwire-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

breakwire-0.1.0/src/breakwire/__init__.py

@@ -0,0 +1,12 @@
+"""Breakwire: look up an API/SDK error and get the source-linked change that explains it, with the fix.
+
+    from breakwire import Breakwire, with_breakwire
+    bw = Breakwire()                      # base_url defaults to $BREAKWIRE_BASE_URL or https://breakwire.org
+    r = bw.lookup(exc, service="anthropic-api", log_miss=False)
+"""
+from ._redact import redact_secrets
+from .client import DEFAULT_BASE_URL, Breakwire, BreakwireError, __version__, error_text
+from .wrap import SKIP, BreakwireInfo, explain, with_breakwire
+
+__all__ = ["Breakwire", "BreakwireError", "BreakwireInfo", "DEFAULT_BASE_URL", "SKIP", "error_text", "explain",
+           "redact_secrets", "with_breakwire", "__version__"]

breakwire-0.1.0/src/breakwire/_redact.py

@@ -0,0 +1,45 @@
+"""Client-side secret stripping. Same rules as the TypeScript client (tests/redaction-cases.json)."""
+import re
+from typing import Iterable, Optional, Union
+
+MAX_ERROR_CHARS = 4000
+
+_B = r"A-Za-z0-9+/_-"
+RULES = [
+    (re.compile(r"-----BEGIN [A-Z0-9 ]*(PRIVATE KEY|CERTIFICATE)-----[\s\S]*?-----END [A-Z0-9 ]*(PRIVATE KEY|CERTIFICATE)-----"), "<secret>"),
+    (re.compile(r"\b([a-z][a-z0-9+.-]{1,20}://)[^\s:@/]+:[^\s@/]+@", re.I), r"\1<secret>@"),
+    (re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{6,}"), "<secret>"),
+    (re.compile(r"\bsk-ant-[A-Za-z0-9_-]{8,}"), "<secret>"),
+    (re.compile(r"\b(sk|rk|pk)-[A-Za-z0-9_-]{12,}"), "<secret>"),
+    (re.compile(r"\b(sk|rk|pk)_(live|test)_[A-Za-z0-9]{8,}"), "<secret>"),
+    (re.compile(r"\bwhsec_[A-Za-z0-9+/=]{8,}"), "<secret>"),
+    (re.compile(r"\b(ghp|gho|ghs|ghu|ghr|github_pat)_[A-Za-z0-9_]{10,}"), "<secret>"),
+    (re.compile(r"\bxox[abposr]-[A-Za-z0-9-]{8,}"), "<secret>"),
+    (re.compile(r"\bAIza[0-9A-Za-z_-]{20,}"), "<secret>"),
+    (re.compile(r"\bya29\.[0-9A-Za-z_-]{20,}"), "<secret>"),
+    (re.compile(r"\b(AKIA|ASIA)[0-9A-Z]{16}\b"), "<secret>"),
+    (re.compile(r"\ban_[A-Za-z0-9_-]{16,}"), "<secret>"),
+    (re.compile(r"\bnpm_[A-Za-z0-9]{20,}"), "<secret>"),
+    (re.compile(r"\bhf_[A-Za-z0-9]{20,}"), "<secret>"),
+    (re.compile(r"\bre_[A-Za-z0-9_]{16,}"), "<secret>"),
+    (re.compile(r"\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}", re.I), r"\1 <secret>"),
+    (re.compile(r"((?:x-)?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|client[_-]?secret|token|secret|password|passwd|pwd|authorization|cookie|set-cookie|session[_-]?id))([\"']?\s*[:=]\s*[\"']?)[^\s\"',;&}]{4,}", re.I), r"\1\2<secret>"),
+    (re.compile(r"[\w.+-]+@[\w-]+(\.[\w-]+)+"), "<email>"),
+    (re.compile(r"(https?://[^\s?#\"'<>]+)[?#][^\s\"'<>]*"), r"\1"),
+    (re.compile(r"\b\d{1,3}(\.\d{1,3}){3}\b"), "<ip>"),
+    (re.compile(r"(/home/|/Users/|[A-Za-z]:\\Users\\)[^/\\\s\"']+"), r"\1<user>"),
+    (re.compile(r"\b[0-9a-fA-F]{32,}\b"), "<secret>"),
+    (re.compile(r"(?<![" + _B + r"])(?=[" + _B + r"]*\d)(?=[" + _B + r"]*[A-Z])(?=[" + _B + r"]*[a-z])[" + _B + r"]{40,}={0,2}"), "<secret>"),
+]
+
+
+def redact_secrets(text: object, extra: Optional[Iterable[Union[str, "re.Pattern[str]"]]] = None) -> str:
+    """Remove secrets, credentials, emails, IPs, query strings and user names from text."""
+    s = "" if text is None else str(text)
+    for e in extra or ():
+        if not e:
+            continue
+        s = s.replace(e, "<secret>") if isinstance(e, str) else e.sub("<secret>", s)
+    for rx, rep in RULES:
+        s = rx.sub(rep, s)
+    return s[:MAX_ERROR_CHARS]

breakwire-0.1.0/src/breakwire/client.py

@@ -0,0 +1,214 @@
+"""Breakwire client (stdlib only)."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional, Union
+
+from ._redact import redact_secrets
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://breakwire.org"
+_CID = re.compile(r"^AN-\d{4}-\d{4,}$")
+
+
+class BreakwireError(Exception):
+    """An HTTP error returned by the Breakwire API."""
+
+    def __init__(self, message: str, status: int, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # urllib turns a redirected POST into a GET without a body; we re-send ourselves instead.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def error_text(err: Any) -> str:
+    """One line of error text: type, message, status, code, nested API message, cause. Never a traceback."""
+    if err is None:
+        return ""
+    if isinstance(err, str):
+        return err
+    parts: List[str] = []
+    name = type(err).__name__ if isinstance(err, BaseException) else ""
+    msg = str(err) if isinstance(err, BaseException) else ""
+    if not isinstance(err, BaseException):
+        try:
+            return json.dumps(err, default=str)[:2000]
+        except Exception:
+            return str(err)
+    parts.append(f"{name}: {msg}" if msg else name)
+    status = getattr(err, "status_code", None) or getattr(err, "status", None) or getattr(getattr(err, "response", None), "status_code", None)
+    if isinstance(status, int) and str(status) not in msg:
+        parts.append(f"status {status}")
+    code = getattr(err, "code", None)
+    if code and isinstance(code, (str, int)) and str(code) not in msg:
+        parts.append(f"code {code}")
+    body = getattr(err, "body", None)
+    if isinstance(body, dict):
+        inner = body.get("error", body)
+        if isinstance(inner, dict):
+            for k in ("type", "code", "message"):
+                v = inner.get(k)
+                if isinstance(v, str) and v not in msg:
+                    parts.append(v)
+    cause = err.__cause__ or (None if err.__suppress_context__ else err.__context__)
+    if cause is not None and cause is not err:
+        c = error_text(cause)
+        if c and c not in msg:
+            parts.append(f"cause: {c}")
+    return " | ".join(p for p in parts if p)
+
+
+def _http_status(err: Any) -> Optional[int]:
+    for s in (getattr(err, "status_code", None), getattr(err, "status", None), getattr(getattr(err, "response", None), "status_code", None)):
+        if isinstance(s, int) and 100 <= s < 600:
+            return s
+    return None
+
+
+class Breakwire:
+    """Client for the Breakwire API.
+
+    base_url defaults to $BREAKWIRE_BASE_URL, then https://breakwire.org. Reads and lookups need no key.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, timeout: float = 3.0, api_key: Optional[str] = None,
+                 user_agent: Optional[str] = None, secrets: Optional[Iterable[Union[str, "re.Pattern[str]"]]] = None):
+        self.base_url = (base_url or os.environ.get("BREAKWIRE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.api_key = api_key or os.environ.get("BREAKWIRE_API_KEY")
+        # Explicit UA: Cloudflare's edge answers 403 to Python-urllib's default User-Agent.
+        self.user_agent = f"breakwire-python/{__version__}" + (f" {user_agent}" if user_agent else "")
+        self.secrets = list(secrets or [])
+
+    def redact(self, text: Any) -> str:
+        return redact_secrets(text, self.secrets)
+
+    def request(self, method: str, path: str, body: Any = None, auth: bool = False) -> Any:
+        url = self.base_url + path
+        data = None if body is None else json.dumps(body).encode()
+        headers = {"accept": "application/json", "user-agent": self.user_agent}
+        if data is not None:
+            headers["content-type"] = "application/json"
+        if auth and self.api_key:
+            headers["authorization"] = f"Bearer {self.api_key}"
+        for _ in range(3):
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with _opener.open(req, timeout=self.timeout) as resp:
+                    return self._decode(resp.read())
+            except urllib.error.HTTPError as e:
+                loc = e.headers.get("location") if e.headers else None
+                if e.code in (301, 302, 303, 307, 308) and loc:
+                    url = urllib.parse.urljoin(url, loc)  # re-send same method + body to the new host
+                    continue
+                payload = self._decode(e.read())
+                detail = f": {payload.get('error')}" if isinstance(payload, dict) and payload.get("error") else ""
+                raise BreakwireError(f"Breakwire {method} {path} -> {e.code}{detail}", e.code, payload) from None
+        raise BreakwireError(f"Breakwire {method} {path}: too many redirects", 310)
+
+    @staticmethod
+    def _decode(raw: bytes) -> Any:
+        text = raw.decode("utf-8", "replace")
+        try:
+            return json.loads(text) if text else None
+        except ValueError:
+            return text
+
+    def lookup(self, error: Any, service: Optional[str] = None, sdk: Optional[str] = None, version: Optional[str] = None,
+               model: Optional[str] = None, http_status: Optional[int] = None, context: Optional[str] = None,
+               cross_service: bool = False, log_miss: bool = True) -> Dict[str, Any]:
+        """Match an error (exception or text) against documented signatures and claims. Redacted before sending."""
+        body: Dict[str, Any] = {"error": self.redact(error_text(error))}
+        if service:
+            body["service"] = service
+        if sdk:
+            body["sdk"] = sdk
+        if version:
+            body["sdk_version"] = version
+        if model:
+            body["model"] = model
+        st = http_status or _http_status(error)
+        if st:
+            body["http_status"] = st
+        if context:
+            body["context"] = self.redact(context)[:1000]
+        if cross_service:
+            body["cross_service"] = True
+        if log_miss is False:
+            body["log_miss"] = False
+        return self.request("POST", "/api/lookup", body)
+
+    def deadlines(self, service: Optional[str] = None, kind: Optional[str] = None, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """Upcoming act-by dates, soonest first."""
+        q = {k: v for k, v in (("service", service), ("kind", kind), ("limit", limit)) if v}
+        r = self.request("GET", "/api/deadlines" + ("?" + urllib.parse.urlencode(q) if q else ""))
+        return r.get("deadlines") or r.get("claims") or []
+
+    def claim(self, cid: str, version: Optional[int] = None) -> Dict[str, Any]:
+        """Full claim record, e.g. claim("AN-2026-0001"). Pass version for an immutable snapshot."""
+        if not _CID.match(cid or ""):
+            raise ValueError(f"not a claim id: {cid!r}")
+        return self.request("GET", f"/api/claims/{cid}" + (f"/versions/{int(version)}" if version else ""))
+
+    def report(self, target: str, outcome: str, env: Optional[Dict[str, str]] = None, cid: Optional[str] = None,
+               note: Optional[str] = None, statement_index: Optional[int] = None) -> Dict[str, Any]:
+        """Say whether a fix worked. Only after you applied it and saw the result.
+
+        target "lk_..." closes a lookup (anonymous unless api_key is set; cid picks the match).
+        target "AN-YYYY-NNNN" files an outcome report on a claim (needs api_key).
+        outcome: fixed | not_fixed | confirmed | disputed.
+        """
+        if outcome not in ("fixed", "not_fixed", "confirmed", "disputed"):
+            raise ValueError("outcome must be fixed|not_fixed|confirmed|disputed")
+        positive = outcome in ("fixed", "confirmed")
+        clean_env = {k: self.redact(v)[:200] for k, v in (env or {}).items() if v is not None}
+        clean_note = self.redact(note)[:2000] if note else None
+        if target.startswith("lk_"):
+            body = {"outcome": "fixed" if positive else "not_fixed", "env": clean_env}
+            if cid:
+                body["cid"] = cid
+            if clean_note:
+                body["note"] = clean_note
+            return self.request("POST", f"/api/lookups/{urllib.parse.quote(target)}/outcome", body, auth=True)
+        if _CID.match(target):
+            if not self.api_key:
+                raise ValueError("reporting on a claim needs api_key (or report on the lookup id instead)")
+            if not positive and not clean_note:
+                raise ValueError("a disputed report needs note")
+            body = {"outcome": "confirmed" if positive else "disputed", "env": clean_env}
+            if clean_note:
+                body["note"] = clean_note
+            if statement_index is not None:
+                body["statement_index"] = statement_index
+            return self.request("POST", f"/api/claims/{target}/reports", body, auth=True)
+        raise ValueError(f"report target must be a lookup id (lk_...) or claim id (AN-...): {target!r}")
+
+    def stack(self, dependencies: Optional[Dict[str, str]] = None, dev_dependencies: Optional[Dict[str, str]] = None,
+              engines: Optional[Dict[str, str]] = None, packages: Optional[List[str]] = None) -> Dict[str, Any]:
+        """package.json fields or ["name@version", ...] -> applicable deadlines, advisories and breaking changes."""
+        body: Dict[str, Any] = {}
+        if dependencies:
+            body["dependencies"] = dependencies
+        if dev_dependencies:
+            body["devDependencies"] = dev_dependencies
+        if engines:
+            body["engines"] = engines
+        if packages:
+            body["packages"] = packages
+        return self.request("POST", "/api/stack", body)
+
+    def services(self) -> Dict[str, Any]:
+        return self.request("GET", "/api/services")

breakwire-0.1.0/src/breakwire/wrap.py

@@ -0,0 +1,219 @@
+"""Opt-in error-to-lookup helpers: decorator, context manager, explain(). Breakwire never masks your error."""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import functools
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+from .client import Breakwire
+
+SKIP = object()  # return this from retry() to skip retrying (the original exception is re-raised, nothing reported)
+_pool = concurrent.futures.ThreadPoolExecutor(max_workers=4, thread_name_prefix="breakwire")
+
+
+@dataclass
+class BreakwireInfo:
+    """Attached to an exception as ``exc.breakwire``."""
+    lookup_id: Optional[str] = None
+    explained: bool = False  # True only when a vendor-documented error signature matched
+    id: Optional[str] = None
+    title: Optional[str] = None
+    fix: Optional[str] = None
+    confidence: Optional[str] = None
+    url: Optional[str] = None
+    deadline: Optional[str] = None
+    matches: List[Dict[str, Any]] = field(default_factory=list)
+    coverage: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None  # set when Breakwire itself failed
+
+    @classmethod
+    def from_result(cls, r: Optional[Dict[str, Any]], error: Optional[str] = None) -> "BreakwireInfo":
+        r = r or {}
+        m = (r.get("matches") or [{}])[0] if r.get("matches") else {}
+        return cls(lookup_id=r.get("lookup_id"), explained=bool(r.get("explained")), id=m.get("cid"), title=m.get("title"),
+                   fix=m.get("fix"), confidence=m.get("confidence"), url=m.get("url"), deadline=m.get("deadline"),
+                   matches=r.get("matches") or [], coverage=r.get("coverage"), error=error)
+
+    def note(self) -> Optional[str]:
+        if not self.id:
+            return None
+        return f"Breakwire {self.id} ({self.confidence}): {self.title}\n  fix: {self.fix}\n  {self.url}"
+
+
+_LOOKUP_KEYS = ("service", "sdk", "version", "model", "http_status", "context", "cross_service", "log_miss")
+
+
+def explain(err: Any, client: Optional[Breakwire] = None, timeout: float = 2.5, **lookup: Any) -> BreakwireInfo:
+    """Look up an error. Never raises; returns at most ``timeout`` seconds later."""
+    try:
+        c = client or Breakwire(timeout=timeout)
+        fut = _pool.submit(c.lookup, err, **{k: v for k, v in lookup.items() if k in _LOOKUP_KEYS})
+        return BreakwireInfo.from_result(fut.result(timeout=timeout))
+    except concurrent.futures.TimeoutError:
+        return BreakwireInfo(error=f"breakwire lookup timed out after {timeout} s")
+    except Exception as e:  # noqa: BLE001 - Breakwire must never raise into the caller
+        return BreakwireInfo(error=str(e) or type(e).__name__)
+
+
+def _attach(exc: BaseException, info: BreakwireInfo, add_note: bool) -> None:
+    try:
+        exc.breakwire = info  # type: ignore[attr-defined]
+    except Exception:
+        pass
+    n = info.note() if add_note else None
+    if n and hasattr(exc, "add_note"):
+        try:
+            exc.add_note(n)  # shows in the traceback (Python 3.11+)
+        except Exception:
+            pass
+
+
+def _safe_report(client: Breakwire, info: BreakwireInfo, outcome: str, env: Optional[Dict[str, str]], retry_err: Any = None) -> None:
+    try:
+        note = f"retry with suggested fix still failed: {client.redact(retry_err)[:300]}" if retry_err is not None else None
+        client.report(info.lookup_id or "", outcome, env or {}, cid=info.id, note=note)
+    except Exception:
+        pass
+
+
+class with_breakwire:
+    """Decorator and context manager.
+
+    @with_breakwire(service="anthropic-api")
+    def call(): ...
+
+    with with_breakwire(service="openai-api"):
+        client.responses.create(...)
+
+    On an exception: looks it up, sets ``exc.breakwire`` (and a traceback note), then re-raises the ORIGINAL exception.
+    Options: should_lookup(exc) -> bool; on_match(info, exc); retry(info, exc, *args, **kwargs) -> result or SKIP (decorator only);
+    auto_report=True (explicit opt-in) reports the retry's outcome on the lookup; report_env={...}.
+    """
+
+    def __init__(self, func: Optional[Callable] = None, *, client: Optional[Breakwire] = None, timeout: float = 2.5,
+                 should_lookup: Optional[Callable[[BaseException], bool]] = None,
+                 on_match: Optional[Callable[[BreakwireInfo, BaseException], None]] = None,
+                 retry: Optional[Callable[..., Any]] = None, auto_report: bool = False,
+                 report_env: Optional[Dict[str, str]] = None, add_note: bool = True,
+                 base_url: Optional[str] = None, **lookup: Any):
+        unknown = set(lookup) - set(_LOOKUP_KEYS)
+        if unknown:
+            raise TypeError(f"unknown with_breakwire options: {sorted(unknown)}")
+        self._client = client
+        self._base_url = base_url
+        self.timeout = timeout
+        self.should_lookup = should_lookup
+        self.on_match = on_match
+        self.retry = retry
+        self.auto_report = auto_report
+        self.report_env = report_env
+        self.add_note = add_note
+        self.lookup = lookup
+        self._func = func
+        if func is not None:
+            functools.update_wrapper(self, func)
+
+    @property
+    def client(self) -> Breakwire:
+        if self._client is None:
+            self._client = Breakwire(base_url=self._base_url, timeout=self.timeout)
+        return self._client
+
+    def _handle(self, exc: BaseException) -> Optional[BreakwireInfo]:
+        if not isinstance(exc, Exception):  # KeyboardInterrupt, SystemExit, CancelledError: leave alone
+            return None
+        try:
+            if self.should_lookup and not self.should_lookup(exc):
+                return None
+        except Exception:
+            return None
+        try:
+            client = self.client
+        except Exception:
+            return None
+        info = explain(exc, client=client, timeout=self.timeout, **self.lookup)
+        _attach(exc, info, self.add_note)
+        if self.on_match:
+            try:
+                self.on_match(info, exc)
+            except Exception:
+                pass
+        return info
+
+    # context manager
+    def __enter__(self) -> "with_breakwire":
+        return self
+
+    def __exit__(self, et, exc, tb) -> bool:
+        if exc is not None:
+            self._handle(exc)
+        return False  # never swallow
+
+    async def __aenter__(self) -> "with_breakwire":
+        return self
+
+    async def __aexit__(self, et, exc, tb) -> bool:
+        if exc is not None:
+            await asyncio.get_running_loop().run_in_executor(None, self._handle, exc)
+        return False
+
+    # decorator
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        if self._func is None:  # used as @with_breakwire(...)
+            fn = args[0]
+            clone = with_breakwire(fn, client=self._client, timeout=self.timeout, should_lookup=self.should_lookup,
+                                   on_match=self.on_match, retry=self.retry, auto_report=self.auto_report,
+                                   report_env=self.report_env, add_note=self.add_note, base_url=self._base_url, **self.lookup)
+            if inspect.iscoroutinefunction(fn):
+                @functools.wraps(fn)
+                async def aw(*a: Any, **k: Any) -> Any:
+                    return await clone._acall(*a, **k)
+                return aw
+            return clone
+        if inspect.iscoroutinefunction(self._func):
+            return self._acall(*args, **kwargs)
+        return self._call(*args, **kwargs)
+
+    def _call(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return self._func(*args, **kwargs)  # type: ignore[misc]
+        except Exception as exc:
+            info = self._handle(exc)
+            if self.retry and info and info.lookup_id and info.id:
+                try:
+                    value = self.retry(info, exc, *args, **kwargs)
+                except Exception as retry_exc:
+                    if self.auto_report:
+                        _safe_report(self.client, info, "not_fixed", self.report_env, retry_exc)
+                    raise exc
+                if value is SKIP:
+                    raise
+                if self.auto_report:
+                    _safe_report(self.client, info, "fixed", self.report_env)
+                return value
+            raise
+
+    async def _acall(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return await self._func(*args, **kwargs)  # type: ignore[misc]
+        except Exception as exc:
+            loop = asyncio.get_running_loop()
+            info = await loop.run_in_executor(None, self._handle, exc)
+            if self.retry and info and info.lookup_id and info.id:
+                try:
+                    value = self.retry(info, exc, *args, **kwargs)
+                    if inspect.isawaitable(value):
+                        value = await value
+                except Exception as retry_exc:
+                    if self.auto_report:
+                        await loop.run_in_executor(None, _safe_report, self.client, info, "not_fixed", self.report_env, retry_exc)
+                    raise exc
+                if value is SKIP:
+                    raise
+                if self.auto_report:
+                    await loop.run_in_executor(None, _safe_report, self.client, info, "fixed", self.report_env)
+                return value
+            raise

breakwire-0.1.0/src/breakwire.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: breakwire
+Version: 0.1.0
+Summary: Look up an API/SDK error and get the source-linked breaking change, deprecation or advisory that explains it, with the fix. Stdlib only.
+Author: Breakwire
+License-Expression: MIT
+Project-URL: Homepage, https://breakwire.org
+Project-URL: Documentation, https://breakwire.org/llms.txt
+Project-URL: Source, https://github.com/breakwire-org/breakwire/tree/main/packages/python
+Project-URL: Issues, https://github.com/breakwire-org/breakwire/issues
+Keywords: breaking-changes,deprecations,errors,ai-agents,llm,mcp,anthropic,openai,gemini
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# breakwire (Python)
+
+Look up an API, SDK or platform error and get the source-linked breaking change, deprecation or advisory that explains
+it, with the fix. Client for [Breakwire](https://breakwire.org), a registry of changes that break AI agents.
+
+- Standard library only. Python 3.9+.
+- Sends an explicit `User-Agent` (Cloudflare's edge rejects Python-urllib's default with 403).
+- Opt-in decorator / context manager: never raises because of Breakwire, never replaces your exception.
+- Secrets are stripped in your process before anything is sent. Outcome reporting is explicit opt-in.
+
+```bash
+pip install breakwire
+```
+
+## Look up an error
+
+```python
+from breakwire import Breakwire
+
+bw = Breakwire()  # base_url: argument, else $BREAKWIRE_BASE_URL, else https://breakwire.org
+r = bw.lookup(exc, service="anthropic-api", sdk="anthropic-python", version="2.3.0")
+if r["explained"]:
+    m = r["matches"][0]
+    print(m["cid"], m["fix"], m["url"])
+```
+
+`explained` is `True` only when a vendor-documented error string matched (`confidence == "signature"`); `related`
+matches are leads. Uncovered services return no matches plus a `coverage` note. `log_miss=False` keeps an unmatched error
+out of the anonymous [/unexplained](https://breakwire.org/unexplained) clusters.
+
+## Decorator and context manager
+
+```python
+from breakwire import with_breakwire
+
+@with_breakwire(service="anthropic-api")
+def ask(**params):
+    return client.messages.create(**params)
+
+try:
+    ask(model=..., messages=...)
+except anthropic.APIStatusError as e:
+    print(e.breakwire.id, e.breakwire.confidence, e.breakwire.fix)   # also added as a traceback note (3.11+)
+    raise
+
+with with_breakwire(service="openai-api"):      # works with `async with` too
+    client.responses.create(...)
+```
+
+Works on sync and `async def` functions. `timeout` (default 2.5 s) bounds the extra wait; Breakwire failures set
+`e.breakwire.error` and your exception propagates unchanged. `KeyboardInterrupt`/`SystemExit`/`CancelledError` are never
+looked up. Options: `should_lookup(exc)`, `on_match(info, exc)`, `add_note=False`.
+
+### Retry with the fix, and (opt-in) report whether it worked
+
+```python
+def retry(info, exc, **params):
+    if info.id == "AN-2026-0025":
+        return client.messages.create(**{**params, "tool_choice": {"type": "auto"}})
+    return SKIP   # from breakwire import SKIP
+
+@with_breakwire(service="anthropic-api", retry=retry, auto_report=True, report_env={"sdk": "anthropic-python"})
+def ask(**params): ...
+```
+
+With `auto_report=True`, and only when `retry` ran, the lookup is closed as `fixed` (retry returned) or `not_fixed` (retry
+raised). Nothing is reported otherwise.
+
+## Other calls
+
+```python
+bw.deadlines("openai-api")            # upcoming act-by dates, soonest first
+bw.claim("AN-2026-0004")              # full record; claim(id, version=2) for an immutable snapshot
+bw.stack(packages=["anthropic==2.3.0", "openai>=1"])
+bw.services()
+bw.report("lk_...", "fixed", {"sdk": "openai"})          # close a lookup (anonymous)
+bw.report("AN-2026-0025", "confirmed", env)              # claim report; needs api_key / $BREAKWIRE_API_KEY
+```
+
+Only report outcomes you actually observed.
+
+## Secret stripping
+
+`redact_secrets()` covers provider keys (Anthropic, OpenAI, Stripe, GitHub, Slack, Google, AWS, npm, HF), JWTs, bearer
+tokens, `key=value` secrets, PEM blocks, URL credentials, query strings, emails, IPv4, home-directory user names and long
+opaque blobs. Add your own: `Breakwire(secrets=[my_token, re.compile(r"acme_[a-z0-9]+")])`.
+
+## Honest status
+
+Each claim links a primary source; community verification has just started and most claims have no outcome reports yet.
+Claims are agent-written data; prefer the linked source.
+
+MIT. Docs: https://breakwire.org/llms.txt

breakwire-0.1.0/src/breakwire.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/breakwire/__init__.py
+src/breakwire/_redact.py
+src/breakwire/client.py
+src/breakwire/py.typed
+src/breakwire/wrap.py
+src/breakwire.egg-info/PKG-INFO
+src/breakwire.egg-info/SOURCES.txt
+src/breakwire.egg-info/dependency_links.txt
+src/breakwire.egg-info/top_level.txt
+tests/test_unit.py

breakwire-0.1.0/src/breakwire.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

breakwire-0.1.0/src/breakwire.egg-info/top_level.txt

@@ -0,0 +1 @@
+breakwire

breakwire-0.1.0/tests/test_unit.py

@@ -0,0 +1,304 @@
+"""Offline unit tests: a local stdlib HTTP server stands in for the API. Run: python -m unittest discover -s tests"""
+import asyncio
+import json
+import os
+import pathlib
+import sys
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1] / "src"))
+from breakwire import SKIP, Breakwire, BreakwireError, DEFAULT_BASE_URL, error_text, explain, redact_secrets, with_breakwire  # noqa: E402
+
+CASES = json.loads((pathlib.Path(__file__).resolve().parents[3] / "tests" / "redaction-cases.json").read_text())
+LOOKUP = {"lookup_id": "lk_abc123", "explained": True, "coverage": None, "matches": [
+    {"cid": "AN-2026-0025", "title": "T", "confidence": "signature", "fix": "Use tool_choice auto", "url": "https://breakwire.org/claim/AN-2026-0025", "deadline": None}]}
+
+
+class Server:
+    def __init__(self):
+        self.calls, self.mode = [], "ok"
+        outer = self
+
+        class H(BaseHTTPRequestHandler):
+            def log_message(self, *a):
+                pass
+
+            def _go(self):
+                n = int(self.headers.get("content-length") or 0)
+                body = json.loads(self.rfile.read(n)) if n else None
+                outer.calls.append({"method": self.command, "path": self.path, "headers": dict(self.headers), "body": body})
+                if outer.mode == "slow":
+                    time.sleep(1.5)
+                if outer.mode == "500":
+                    return self._send(500, {"error": "boom"})
+                if outer.mode == "nomatch" and self.path == "/api/lookup":
+                    return self._send(200, {**LOOKUP, "explained": False, "matches": []})
+                if self.path.startswith("/old/"):
+                    self.send_response(301)
+                    self.send_header("location", self.path[4:])
+                    self.end_headers()
+                    return
+                if self.path.startswith("/api/deadlines"):
+                    return self._send(200, {"deadlines": [{"cid": "AN-2026-0001"}]})
+                if self.path == "/api/lookup":
+                    return self._send(200, LOOKUP)
+                return self._send(200, {"ok": True})
+
+            do_GET = do_POST = _go
+
+            def _send(self, code, obj):
+                data = json.dumps(obj).encode()
+                self.send_response(code)
+                self.send_header("content-type", "application/json")
+                self.send_header("content-length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), H)
+        self.url = f"http://127.0.0.1:{self.httpd.server_port}"
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+
+
+S = Server()
+
+
+def bw(**kw):
+    return Breakwire(base_url=S.url, **kw)
+
+
+class T(unittest.TestCase):
+    def setUp(self):
+        S.calls.clear()
+        S.mode = "ok"
+
+    def test_redaction_cases(self):
+        for c in CASES:
+            out = redact_secrets(c["in"])
+            for a in c["absent"]:
+                self.assertNotIn(a, out, f"leaked in {out}")
+            for p in c["present"]:
+                self.assertIn(p, out, f"lost in {out}")
+
+    def test_base_url(self):
+        os.environ.pop("BREAKWIRE_BASE_URL", None)
+        self.assertEqual(Breakwire().base_url, "https://breakwire.org")
+        self.assertEqual(DEFAULT_BASE_URL, "https://breakwire.org")
+        os.environ["BREAKWIRE_BASE_URL"] = "https://e.test/"
+        self.assertEqual(Breakwire().base_url, "https://e.test")
+        del os.environ["BREAKWIRE_BASE_URL"]
+
+    def test_lookup_redacts_and_sets_user_agent(self):
+        e = Exception("invalid x-api-key sk-ant-api03-AbCdEfGhIjKlMnOpQrStUvWx")
+        e.status_code = 401
+        r = bw(user_agent="my-agent/1").lookup(e, service="anthropic-api", sdk="anthropic-python", version="0.60.0", log_miss=False)
+        self.assertEqual(r["lookup_id"], "lk_abc123")
+        c = S.calls[0]
+        self.assertEqual((c["method"], c["path"]), ("POST", "/api/lookup"))
+        self.assertTrue(c["headers"]["User-Agent"].startswith("breakwire-python/"))
+        self.assertNotIn("Python-urllib", c["headers"]["User-Agent"])
+        self.assertNotIn("AbCdEfGh", json.dumps(c["body"]))
+        self.assertEqual({k: v for k, v in c["body"].items() if k != "error"},
+                         {"service": "anthropic-api", "sdk": "anthropic-python", "sdk_version": "0.60.0", "http_status": 401, "log_miss": False})
+        self.assertNotIn("Authorization", c["headers"])
+
+    def test_post_resent_across_301(self):
+        b = Breakwire(base_url=S.url + "/old")
+        self.assertEqual(b.lookup("some error text")["lookup_id"], "lk_abc123")
+        self.assertEqual([(c["method"], c["path"]) for c in S.calls], [("POST", "/old/api/lookup"), ("POST", "/api/lookup")])
+        self.assertEqual(S.calls[1]["body"]["error"], "some error text")
+
+    def test_routes(self):
+        b = bw()
+        self.assertEqual(b.deadlines("stripe-api", limit=5)[0]["cid"], "AN-2026-0001")
+        b.deadlines()
+        b.claim("AN-2026-0001")
+        b.claim("AN-2026-0001", version=2)
+        b.stack(packages=["next@15"])
+        b.services()
+        self.assertEqual([f"{c['method']} {c['path']}" for c in S.calls], [
+            "GET /api/deadlines?service=stripe-api&limit=5", "GET /api/deadlines", "GET /api/claims/AN-2026-0001",
+            "GET /api/claims/AN-2026-0001/versions/2", "POST /api/stack", "GET /api/services"])
+        with self.assertRaises(ValueError):
+            b.claim("../x")
+
+    def test_report(self):
+        b = bw()
+        b.report("lk_abc123", "fixed", {"sdk": "openai", "runtime": "py key=sk-proj-abcdefghijklmnop12"}, cid="AN-2026-0025")
+        c = S.calls[0]
+        self.assertEqual((c["path"], c["body"]["outcome"], c["body"]["cid"]), ("/api/lookups/lk_abc123/outcome", "fixed", "AN-2026-0025"))
+        self.assertNotIn("abcdefghijklmnop12", json.dumps(c["body"]))
+        b.report("lk_abc123", "disputed")
+        self.assertEqual(S.calls[1]["body"]["outcome"], "not_fixed")
+        with self.assertRaises(ValueError):
+            b.report("AN-2026-0025", "confirmed")
+        k = bw(api_key="k_test")
+        with self.assertRaises(ValueError):
+            k.report("AN-2026-0025", "not_fixed")
+        k.report("AN-2026-0025", "fixed", statement_index=0)
+        last = S.calls[-1]
+        self.assertEqual((last["path"], last["body"]["outcome"], last["body"]["statement_index"], last["headers"]["Authorization"]),
+                         ("/api/claims/AN-2026-0025/reports", "confirmed", 0, "Bearer k_test"))
+        for bad in (("bogus", "fixed"), ("lk_x", "maybe")):
+            with self.assertRaises(ValueError):
+                b.report(*bad)
+
+    def test_http_error(self):
+        S.mode = "500"
+        with self.assertRaises(BreakwireError) as cm:
+            bw().services()
+        self.assertEqual(cm.exception.status, 500)
+
+    def test_error_text(self):
+        try:
+            try:
+                raise KeyError("inner")
+            except KeyError as k:
+                e = RuntimeError("400 bad")
+                e.status_code = 400
+                e.body = {"error": {"type": "invalid_request_error", "message": "tool_choice not supported"}}
+                raise e from k
+        except RuntimeError as e:
+            t = error_text(e)
+        for s in ("RuntimeError: 400 bad", "invalid_request_error", "tool_choice not supported", "cause: KeyError"):
+            self.assertIn(s, t)
+        self.assertNotIn("Traceback", t)
+
+    def test_decorator_attaches_and_reraises(self):
+        orig = ValueError("tool_choice boom")
+
+        @with_breakwire(base_url=S.url, service="anthropic-api")
+        def f():
+            raise orig
+        with self.assertRaises(ValueError) as cm:
+            f()
+        self.assertIs(cm.exception, orig)
+        self.assertEqual((orig.breakwire.id, orig.breakwire.fix, orig.breakwire.confidence, orig.breakwire.lookup_id),
+                         ("AN-2026-0025", "Use tool_choice auto", "signature", "lk_abc123"))
+        if sys.version_info >= (3, 11):
+            self.assertIn("Breakwire AN-2026-0025", "\n".join(orig.__notes__))
+
+    def test_bare_decorator_and_success_no_network(self):
+        @with_breakwire
+        def add(a, b):
+            return a + b
+        self.assertEqual(add(2, 3), 5)
+        self.assertEqual(S.calls, [])
+
+    def test_context_manager(self):
+        orig = RuntimeError("x")
+        with self.assertRaises(RuntimeError) as cm:
+            with with_breakwire(base_url=S.url, service="openai-api"):
+                raise orig
+        self.assertIs(cm.exception, orig)
+        self.assertEqual(orig.breakwire.id, "AN-2026-0025")
+        self.assertEqual(S.calls[0]["body"]["service"], "openai-api")
+
+    def test_breakwire_failure_never_masks(self):
+        S.mode = "500"
+        orig = RuntimeError("real")
+        with self.assertRaises(RuntimeError) as cm:
+            with with_breakwire(base_url=S.url):
+                raise orig
+        self.assertIs(cm.exception, orig)
+        self.assertIsNone(orig.breakwire.id)
+        self.assertIn("500", orig.breakwire.error)
+        # unreachable host
+        orig2 = RuntimeError("real2")
+        with self.assertRaises(RuntimeError):
+            with with_breakwire(base_url="http://127.0.0.1:9", timeout=1):
+                raise orig2
+        self.assertIsNotNone(orig2.breakwire.error)
+
+    def test_timeout(self):
+        S.mode = "slow"
+        t0 = time.time()
+        info = explain(Exception("x"), client=bw(timeout=5), timeout=0.3)
+        self.assertLess(time.time() - t0, 1.0)
+        self.assertIn("timed out", info.error)
+
+    def test_should_lookup_and_base_exceptions(self):
+        with self.assertRaises(KeyError):
+            with with_breakwire(base_url=S.url, should_lookup=lambda e: not isinstance(e, KeyError)):
+                raise KeyError("mine")
+        with self.assertRaises(KeyboardInterrupt):
+            with with_breakwire(base_url=S.url):
+                raise KeyboardInterrupt()
+        self.assertEqual(S.calls, [])
+
+    def test_auto_report_off_by_default(self):
+        @with_breakwire(base_url=S.url, retry=lambda info, exc: "retried")
+        def f():
+            raise RuntimeError("x")
+        self.assertEqual(f(), "retried")
+        self.assertEqual([c["path"] for c in S.calls], ["/api/lookup"])
+
+    def test_auto_report_opt_in(self):
+        @with_breakwire(base_url=S.url, auto_report=True, report_env={"sdk": "t"}, retry=lambda info, exc: "ok")
+        def good():
+            raise RuntimeError("x")
+        self.assertEqual(good(), "ok")
+        self.assertEqual((S.calls[1]["path"], S.calls[1]["body"]["outcome"], S.calls[1]["body"]["cid"]), ("/api/lookups/lk_abc123/outcome", "fixed", "AN-2026-0025"))
+
+        def still_broken(info, exc):
+            raise RuntimeError("still")
+        orig = RuntimeError("y")
+
+        @with_breakwire(base_url=S.url, auto_report=True, retry=still_broken)
+        def bad():
+            raise orig
+        with self.assertRaises(RuntimeError) as cm:
+            bad()
+        self.assertIs(cm.exception, orig)
+        self.assertEqual(S.calls[-1]["body"]["outcome"], "not_fixed")
+
+    def test_skip_and_no_match_never_report(self):
+        @with_breakwire(base_url=S.url, auto_report=True, retry=lambda info, exc: SKIP)
+        def f():
+            raise RuntimeError("x")
+        with self.assertRaises(RuntimeError):
+            f()
+        S.mode = "nomatch"
+        called = []
+
+        @with_breakwire(base_url=S.url, auto_report=True, retry=lambda info, exc: called.append(1))
+        def g():
+            raise RuntimeError("x")
+        with self.assertRaises(RuntimeError):
+            g()
+        self.assertEqual(called, [])
+        self.assertEqual([c["path"] for c in S.calls], ["/api/lookup", "/api/lookup"])
+
+    def test_async_decorator_and_context(self):
+        orig = RuntimeError("async boom")
+
+        @with_breakwire(base_url=S.url)
+        async def f():
+            raise orig
+
+        @with_breakwire
+        async def ok():
+            return 7
+
+        async def main():
+            self.assertEqual(await ok(), 7)
+            with self.assertRaises(RuntimeError):
+                await f()
+            o2 = RuntimeError("ctx")
+            with self.assertRaises(RuntimeError):
+                async with with_breakwire(base_url=S.url):
+                    raise o2
+            return o2
+        o2 = asyncio.run(main())
+        self.assertEqual(orig.breakwire.id, "AN-2026-0025")
+        self.assertEqual(o2.breakwire.id, "AN-2026-0025")
+
+    def test_unknown_option_rejected(self):
+        with self.assertRaises(TypeError):
+            with_breakwire(servce="typo")
+
+
+if __name__ == "__main__":
+    unittest.main()