agents-toolkit 1.0.0__py3-none-any.whl

agents_kit/__init__.py

@@ -0,0 +1,15 @@
+"""Agents Kit — the parts of an autonomous agent that fail silently, and how to build them so
+they don't.
+
+Every module here was extracted from a running system after the corresponding failure had
+already cost me weeks. Each one is standalone: copy the file, it has no dependencies beyond
+the standard library.
+
+    webhook_rail  a payment rail that cannot silently lose money
+    gates         quality gates that fail OPEN on "couldn't measure", CLOSED on "measured bad"
+    staleness     catch loops that run forever and produce nothing
+    attention     budget arbitration that proves nothing starves
+    delivery      idempotent fulfilment that never drops a paid order
+"""
+
+__version__ = "1.0.0"

agents_kit/attention.py

@@ -0,0 +1,102 @@
+"""agents_kit/attention.py — spend a tick's compute on what is worth doing, and prove nothing starves.
+
+An agent with more things to do than budget needs an arbiter. Mine scored bids as
+
+    score = (0.4*value + 0.4*info + 0.2*urgency) / cost
+
+and spent greedily under a per-tick budget. Reasonable. It also silently disabled a third of
+the system for months.
+
+The 13 registered bids cost 6.5 units in total. The budget was 3.0. Because greedy-by-ratio
+picks cheap work first, the three most expensive bids — the deep reasoning, the simulation,
+the dreaming, i.e. the entire reason the system was interesting — won **0 of 81** consecutive
+arbitrations. Not "rarely": never. No flag said so, no log said so; the one number that
+disabled them was a tunable nobody thought of as a switch.
+
+Two defences, both here:
+  * `starving()` names any bid that has never won. Alarm on it.
+  * urgency rises the longer a bid goes unchosen, so an expensive bid eventually outbids
+    cheap ones instead of losing on ratio forever.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Bid:
+    """One candidate action competing for this tick."""
+
+    name: str
+    run: object                    # callable, invoked if chosen
+    value: float = 0.5             # expected payoff, 0..1
+    info: float = 0.5              # expected information gain, 0..1
+    cost: float = 1.0              # budget units consumed if it runs
+    stale_after_s: float = 7 * 86400   # urgency saturates at 1.0 after this long unchosen
+
+
+@dataclass
+class Arbiter:
+    budget: float = 5.0
+    w_value: float = 0.4
+    w_info: float = 0.4
+    w_urgency: float = 0.2
+    min_score: float = 0.05
+    _last_run: dict[str, float] = field(default_factory=dict)
+    _wins: dict[str, int] = field(default_factory=dict)
+    _seen: set[str] = field(default_factory=set)
+
+    def urgency(self, bid: Bid) -> float:
+        last = self._last_run.get(bid.name)
+        if last is None:
+            return 1.0                      # never run ⇒ maximally urgent
+        return min(1.0, (time.time() - last) / max(1.0, bid.stale_after_s))
+
+    def score(self, bid: Bid) -> float:
+        raw = (self.w_value * bid.value + self.w_info * bid.info
+               + self.w_urgency * self.urgency(bid))
+        return raw / max(0.01, bid.cost)
+
+    def choose(self, bids: list[Bid]) -> list[Bid]:
+        """Greedy under budget. Pure — does not run anything."""
+        for b in bids:
+            self._seen.add(b.name)
+        ranked = sorted(bids, key=self.score, reverse=True)
+        chosen, spent = [], 0.0
+        for bid in ranked:
+            if self.score(bid) < self.min_score:
+                continue
+            if spent + bid.cost > self.budget:
+                continue
+            chosen.append(bid)
+            spent += bid.cost
+        return chosen
+
+    def run(self, bids: list[Bid]) -> dict:
+        chosen = self.choose(bids)
+        results = {}
+        for bid in chosen:
+            self._last_run[bid.name] = time.time()
+            self._wins[bid.name] = self._wins.get(bid.name, 0) + 1
+            try:
+                results[bid.name] = bid.run() if callable(bid.run) else None
+            except Exception as exc:                          # noqa: BLE001
+                results[bid.name] = f"error: {str(exc)[:120]}"
+        return {"chosen": [b.name for b in chosen], "results": results,
+                "starving": self.starving()}
+
+    def starving(self) -> list[str]:
+        """Bids that have competed but NEVER won. If this is non-empty, either raise the
+        budget or delete the bid — do not leave it registered and dead."""
+        return sorted(n for n in self._seen if not self._wins.get(n))
+
+    def feasible(self, bids: list[Bid]) -> dict:
+        """Sanity check to run at startup, not in production. Compares the budget against what
+        the registered bids actually cost, and warns when the most expensive can never fit."""
+        total = sum(b.cost for b in bids)
+        unaffordable = sorted(b.name for b in bids if b.cost > self.budget)
+        return {"budget": self.budget, "total_cost": round(total, 2),
+                "coverage": round(self.budget / total, 2) if total else 1.0,
+                "never_affordable": unaffordable}

agents_kit/delivery.py

@@ -0,0 +1,107 @@
+"""agents_kit/delivery.py — deliver what was paid for, exactly once, or tell somebody.
+
+The three ways I have actually failed a paying customer:
+
+  1. **Delivered nothing.** Revenue was recorded, no delivery step existed. The buyer paid and
+     got silence. Nothing in the system knew anything was wrong, because the sale looked fine.
+
+  2. **Delivered twice.** The processor retried the webhook and the buyer got two emails.
+     Harmless here; if the deliverable had been a licence key or a credit top-up, it would not
+     have been.
+
+  3. **Delivered a link back to the sales page they had just bought from.** This one is my
+     favourite, because it passed every test. The code collected "the venture's best URL", and
+     the venture's best URL was its own landing page. To the buyer it reads exactly like a
+     scam. It shipped because "a link was produced" was the success condition.
+
+The rules encoded below:
+  * Idempotent per (order, product) — a retry is a no-op, not a second delivery.
+  * A deliverable must be *verified* to be a deliverable, not merely to exist.
+  * NEVER fail silently. If delivery cannot happen, record it as PENDING and alert a human.
+    A paid customer must never be left with nothing and no trace.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Protocol
+
+
+class Store(Protocol):
+    def delivered(self, order_ref: str) -> bool: ...
+    def mark_delivered(self, order_ref: str, to: str, links: list[str]) -> None: ...
+    def mark_pending(self, order_ref: str, to: str, reason: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class Result:
+    status: str            # delivered | duplicate | pending
+    links: list[str]
+    reason: str = ""
+
+
+def usable_links(candidates: Iterable[str], sales_pages: Iterable[str]) -> list[str]:
+    """Filter candidate URLs down to ones a buyer can actually use.
+
+    Rejects, in order of how badly each one burned me:
+      * the sales page itself (and its directory/index twin)
+      * `file://` and localhost paths, which resolve only on the machine that made them —
+        these appear when a publisher silently falls back to a local "dry" mode
+      * empties and duplicates, order preserved
+    """
+    blocked = set()
+    for page in sales_pages:
+        p = (page or "").strip()
+        if not p:
+            continue
+        blocked.add(p)
+        if p.endswith("/index.html"):
+            blocked.add(p[: -len("index.html")])
+        elif p.endswith("/"):
+            blocked.add(p + "index.html")
+
+    out, seen = [], set()
+    for c in candidates:
+        u = (c or "").strip()
+        if not u or u in blocked or u in seen:
+            continue
+        if u.lower().startswith(("file://", "http://127.0.0.1", "http://localhost")):
+            continue
+        seen.add(u)
+        out.append(u)
+    return out
+
+
+def deliver(order_ref: str, to: str, candidates: Iterable[str], sales_pages: Iterable[str],
+            store: Store, send: Callable[[str, list[str]], bool]) -> Result:
+    """Deliver once. Never raises.
+
+    Note what happens when there is nothing good to send: it does NOT fall back to "send the
+    least-bad link". It records PENDING so a human finishes the job. An honest pending beats a
+    delivery the buyer will read as a scam — and unlike the scam, somebody finds out about it.
+    """
+    if store.delivered(order_ref):
+        return Result("duplicate", [], "already delivered")
+
+    if not to or "@" not in to:
+        store.mark_pending(order_ref, to, "no buyer address")
+        return Result("pending", [], "no buyer address")
+
+    links = usable_links(candidates, sales_pages)
+    if not links:
+        store.mark_pending(order_ref, to, "no usable deliverable")
+        return Result("pending", [], "no usable deliverable")
+
+    try:
+        ok = send(to, links)
+    except Exception as exc:                                  # noqa: BLE001
+        store.mark_pending(order_ref, to, f"send raised: {str(exc)[:120]}")
+        return Result("pending", links, "send raised")
+
+    if not ok:
+        store.mark_pending(order_ref, to, "send rejected")
+        return Result("pending", links, "send rejected")
+
+    # Mark only AFTER a confirmed send, so a failure retries instead of being sealed as done.
+    store.mark_delivered(order_ref, to, links)
+    return Result("delivered", links)

agents_kit/gates.py

@@ -0,0 +1,97 @@
+"""agents_kit/gates.py — quality gates that fail OPEN on "couldn't measure" and CLOSED on "measured bad".
+
+The bug this exists to prevent cost me weeks of a pipeline that looked healthy and shipped
+nothing.
+
+A gate scored products with an LLM panel. Its judge looked like this:
+
+    try:
+        verdict = llm.judge(...)
+        return {"success": verdict["success"], "reuse": verdict["reuse"]}
+    except Exception:
+        return {"success": False, "reuse": False}      # <-- the bug
+
+That `except` conflates two completely different facts: "the user said no" and "I could not
+ask the user". When the LLM pool started returning 429s, every judgement became a rejection,
+the score pinned to 0.0, the threshold was 0.5, and the gate blocked every launch — forever.
+The logs showed a busy, green system. 47 blocks, 3 passes, and nobody could see why.
+
+Worse, it was self-sealing: no launch → no page → no traffic → no real usage data → the gate
+fell back to the broken proxy → no launch.
+
+The rule: a gate may only block on evidence. Absence of evidence is UNKNOWN, and UNKNOWN
+must pass through while being loudly recorded.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Sequence
+
+
+class Verdict(str, Enum):
+    PASS = "pass"        # measured, and good enough
+    BLOCK = "block"      # measured, and not good enough
+    UNKNOWN = "unknown"  # could not measure — passes through, but says so
+
+
+@dataclass
+class Judgement:
+    """One judge's answer. `error=True` means the judge never ran."""
+
+    ok: bool = False
+    error: bool = False
+
+
+@dataclass
+class GateResult:
+    verdict: Verdict
+    score: float
+    threshold: float
+    judged: int              # how many judgements actually happened
+    errors: int              # how many failed to run
+    reasons: list[str] = field(default_factory=list)
+
+    @property
+    def allowed(self) -> bool:
+        """UNKNOWN is allowed. This is the whole point of the module."""
+        return self.verdict in (Verdict.PASS, Verdict.UNKNOWN)
+
+
+def evaluate(judges: Sequence[Callable[[], Judgement]], threshold: float = 0.5,
+             enabled: bool = True) -> GateResult:
+    """Run every judge, then decide. Never raises.
+
+    `enabled=False` gives you measure-only mode: the score is still computed and returned, but
+    the verdict is always PASS. Run a new gate this way for a week before you let it block —
+    you want to know what it *would* have done while it can't hurt you.
+    """
+    judged = errors = passed = 0
+    reasons: list[str] = []
+
+    for judge in judges:
+        try:
+            j = judge()
+        except Exception as exc:                              # noqa: BLE001
+            errors += 1
+            reasons.append(f"judge raised: {str(exc)[:80]}")
+            continue
+        if j.error:
+            errors += 1
+            reasons.append("judge could not run")
+            continue
+        judged += 1
+        passed += 1 if j.ok else 0
+
+    if judged == 0:
+        # Nothing was actually measured. Do NOT score this 0.0 and block on it.
+        return GateResult(Verdict.UNKNOWN, 0.0, threshold, 0, errors,
+                          reasons or ["no judge produced a verdict"])
+
+    score = round(passed / judged, 4)
+    if not enabled:
+        return GateResult(Verdict.PASS, score, threshold, judged, errors,
+                          ["gate in measure-only mode"])
+    verdict = Verdict.PASS if score >= threshold else Verdict.BLOCK
+    return GateResult(verdict, score, threshold, judged, errors, reasons)

agents_kit/staleness.py

@@ -0,0 +1,83 @@
+"""agents_kit/staleness.py — catch the machinery that runs and produces nothing.
+
+This is the failure mode that hides best, because every signal you normally watch says fine.
+
+For three weeks a discovery loop logged, every single tick:
+
+    discovery scan ok :: candidates=17 recorded=0
+
+Status `ok`. No exception, no error rate, no latency spike, uptime 100%, dashboards green.
+It evaluated the same 17 candidates and recorded none of them, forever. Alongside it a
+perception loop logged `new=0` for seven days and a falsification loop logged `refuted=0`
+on every tick it had ever run.
+
+Health checks answer "did it run?". Almost nothing answers "did running it change anything?" —
+and for an autonomous system, a step that changes nothing is indistinguishable from a step
+that never ran, except that it also burns your budget.
+
+Track the OUTPUT DELTA, and alarm when it is zero N times running.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _Track:
+    zero_streak: int = 0
+    last_output_at: float = 0.0
+    total_ticks: int = 0
+    total_output: float = 0.0
+
+
+@dataclass
+class StalenessMonitor:
+    """Records per-task output volume and reports which tasks have gone inert.
+
+    >>> m = StalenessMonitor(patience=3)
+    >>> for _ in range(3): _ = m.record("discovery", produced=0)
+    >>> m.stale()
+    ['discovery']
+
+    `produced` is whatever "this tick did something" means for the task: rows written, bytes
+    published, decisions taken. It must be a count of NEW output — an idempotent upsert that
+    rewrites the same 7 rows every tick produces 0, not 7. Getting this wrong is exactly how
+    `found=7 stored=7` read as healthy for a month.
+    """
+
+    patience: int = 5
+    _tracks: dict[str, _Track] = field(default_factory=dict)
+
+    def record(self, task: str, produced: float) -> bool:
+        """Log one tick. Returns True if `task` is now considered stale."""
+        t = self._tracks.setdefault(task, _Track())
+        t.total_ticks += 1
+        if produced > 0:
+            t.zero_streak = 0
+            t.last_output_at = time.time()
+            t.total_output += produced
+        else:
+            t.zero_streak += 1
+        return t.zero_streak >= self.patience
+
+    def stale(self) -> list[str]:
+        """Every task whose last `patience` ticks all produced nothing."""
+        return sorted(k for k, t in self._tracks.items() if t.zero_streak >= self.patience)
+
+    def report(self) -> list[dict]:
+        """Full picture, worst first — drop this straight into a daily brief."""
+        rows = [
+            {
+                "task": k,
+                "zero_streak": t.zero_streak,
+                "ticks": t.total_ticks,
+                "total_output": t.total_output,
+                "idle_hours": round((time.time() - t.last_output_at) / 3600.0, 1)
+                if t.last_output_at else None,
+                "stale": t.zero_streak >= self.patience,
+            }
+            for k, t in self._tracks.items()
+        ]
+        return sorted(rows, key=lambda r: (-r["zero_streak"], r["task"]))

agents_kit/webhook_rail.py

@@ -0,0 +1,144 @@
+"""agents_kit/webhook_rail.py — a payment webhook that cannot silently lose money.
+
+Every failure mode here is one I hit in production, in the order I hit it.
+
+    1. The webhook was registered against the WRONG SERVICE. It had never fired once.
+    2. The signing secret was empty, so verification returned False and every call 401'd —
+       money arrived at the processor, the app recorded nothing, the buyer got nothing.
+    3. Retries double-counted, because "did we already handle this order?" was never asked.
+    4. Test-mode orders booked as real income, so the dashboard showed revenue that did not
+       exist and every downstream gate keyed off a lie.
+
+The rail below is ~120 lines and closes all four. Copy it whole.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+
+class AlreadyHandled(Exception):
+    """Raised by a Ledger when an event id has been seen before."""
+
+
+class Ledger(Protocol):
+    """Your storage. Two operations, both of which must be atomic."""
+
+    def seen(self, event_id: str) -> bool: ...
+    def record(self, event_id: str, amount: float, currency: str, live: bool) -> None: ...
+
+
+@dataclass(frozen=True)
+class Event:
+    """A normalised payment event. `live` is the single most important field on it."""
+
+    id: str
+    kind: str
+    amount: float
+    currency: str
+    email: str
+    live: bool          # False for processor test-mode. NEVER book these as income.
+    reference: str      # your own id (venture/product/customer) from checkout metadata
+    raw: dict
+
+    @property
+    def is_refund(self) -> bool:
+        return self.kind in ("order_refunded", "subscription_payment_refunded")
+
+
+def verify(raw_body: bytes, signature: str, secret: str) -> bool:
+    """Constant-time HMAC-SHA256 check over the RAW body.
+
+    Three rules that are easy to get wrong:
+
+    * Verify the raw bytes, not a re-serialised dict. `json.loads` then `json.dumps` will
+      reorder keys and change whitespace, and the signature will never match again.
+    * An empty secret returns False. It must never mean "skip the check" — an internet-facing
+      revenue route that mints on an unverified call is a free-money endpoint for anyone who
+      finds it.
+    * Compare with `hmac.compare_digest`, not `==`, so the comparison does not leak the
+      expected digest one byte at a time.
+    """
+    if not secret or not signature:
+        return False
+    expected = hmac.new(secret.encode("utf-8"), raw_body or b"", hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature.strip().lower())
+
+
+def parse(raw_body: bytes, event_name: str) -> Event | None:
+    """Normalise a Lemon Squeezy payload. Adapt `attributes` for another processor.
+
+    Returns None rather than raising: a malformed body is a 400, not a 500, and it must not
+    take down the listener that healthy retries depend on.
+    """
+    try:
+        payload = json.loads((raw_body or b"").decode("utf-8", "replace"))
+    except Exception:
+        return None
+    if not isinstance(payload, dict):
+        return None
+
+    data = payload.get("data") or {}
+    attrs = data.get("attributes") or {}
+    meta = payload.get("meta") or {}
+    custom = meta.get("custom_data") or {}
+
+    total = attrs.get("total")
+    try:
+        amount = round(float(total) / 100.0, 2) if total is not None else 0.0
+    except (TypeError, ValueError):
+        amount = 0.0
+
+    return Event(
+        id=str(data.get("id") or attrs.get("identifier") or "").strip(),
+        kind=(event_name or meta.get("event_name") or "").strip(),
+        amount=amount,
+        currency=str(attrs.get("currency") or "USD").upper(),
+        email=str(attrs.get("user_email") or "").strip(),
+        # Missing test_mode is treated as LIVE. A processor always sends it; a payload without
+        # it is not a test order, and defaulting to "test" would hide real income.
+        live=not _truthy(attrs.get("test_mode")),
+        reference=str(custom.get("reference") or custom.get("venture_id") or "").strip(),
+        raw=payload,
+    )
+
+
+def _truthy(value) -> bool:
+    return str(value).strip().lower() in ("1", "true", "yes", "t")
+
+
+def handle(raw_body: bytes, signature: str, event_name: str, secret: str,
+           ledger: Ledger, fulfil: Callable[[Event], None]) -> tuple[int, dict]:
+    """The whole rail. Returns (http_status, body) — wire it straight into your handler.
+
+    Order matters and is not negotiable:
+      verify → parse → dedupe → record → fulfil
+
+    Fulfilment runs LAST and its failure does not roll back the recording. A sale you recorded
+    but failed to deliver is a support ticket; a sale you delivered but failed to record is a
+    hole in your books that nothing will ever surface.
+    """
+    if not verify(raw_body, signature, secret):
+        return 401, {"error": "bad signature"}
+
+    event = parse(raw_body, event_name)
+    if event is None or not event.id:
+        return 400, {"error": "unparseable"}
+
+    if ledger.seen(event.id):
+        # 200, not 409: the processor is retrying and a non-2xx makes it retry harder.
+        return 200, {"status": "duplicate", "id": event.id}
+
+    amount = -event.amount if event.is_refund else event.amount
+    ledger.record(event.id, amount, event.currency, event.live)
+
+    try:
+        fulfil(event)
+    except Exception as exc:                                  # noqa: BLE001 — reported, not raised
+        return 200, {"status": "recorded", "fulfilment": f"pending: {exc}"[:200]}
+
+    return 200, {"status": "ok", "recorded": amount, "live": event.live}

agents_toolkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: agents-toolkit
+Version: 1.0.0
+Summary: Five things an autonomous agent gets wrong silently, and the code that stops each one. Dependency-free stdlib.
+Project-URL: Homepage, https://get-agents-kit.com/agents-kit/
+Author-email: Ahmed Mribai <hello@get-agents-kit.com>
+License: MIT License
+        
+        Copyright (c) 2026 Ahmed Mribai
+        
+        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.
+        
+        ---
+        
+        This MIT licence covers the CODE in agents_kit/ and tests/ only.
+        
+        The written post-mortem sold separately (POSTMORTEM.md and the incident
+        analysis it contains) is not covered by this licence and may not be
+        redistributed. See LICENSE-POSTMORTEM.txt.
+License-File: LICENSE
+License-File: LICENSE-POSTMORTEM.txt
+Keywords: agents,autonomous,fulfilment,idempotency,llm,observability,quality-gates,reliability,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# The Agents Kit
+
+**Five things an autonomous agent gets wrong silently, and the code that stops each one.**
+
+Every module here came out of a system that ran continuously for months, made real decisions,
+published real pages, sent real email — and earned exactly **$0**. Not because it crashed.
+Because each of these five failures is invisible from the outside: the logs stay green, the
+uptime stays 100%, the dashboards keep moving, and nothing works.
+
+This is not a guide to building agents. There are plenty of those. This is the list of ways
+mine failed *while reporting success*, each one reduced to a standalone module with tests.
+
+Every module is dependency-free standard library. Install it, or copy the one file you need —
+both are fine, it's MIT.
+
+```bash
+pip install agents-toolkit
+```
+
+The distribution is `agents-toolkit`; the import is `agents_kit`.
+
+```
+agents_kit.webhook_rail   a payment rail that cannot silently lose money
+agents_kit.gates          gates that fail OPEN on "couldn't measure", CLOSED on "measured bad"
+agents_kit.staleness      catch loops that run forever and produce nothing
+agents_kit.attention      budget arbitration that proves nothing starves
+agents_kit.delivery       idempotent fulfilment that never drops a paid order
+```
+
+29 tests cover all five incidents:
+
+```bash
+pip install pytest && python -m pytest tests/ -q
+```
+
+---
+
+## The first incident, in full
+
+Below is one of the five, complete — the diagnosis, not just the fix — so you can judge the
+rest by it.
+
+### 1. The money rail that had never once fired
+
+**Symptom:** a live product, a working checkout, a correct webhook handler, and $0 recorded.
+
+Four independent breaks, each individually silent, stacked:
+
+- The webhook was registered against **the wrong service** — a sibling backend that did not
+  own fulfilment. `last_sent_at: null`. It had never fired in its life.
+- It was registered in **test mode**, so a real purchase would fire nothing at all.
+- The signing secret was **empty** in the app's vault. `verify()` returned False for every
+  call, so even correctly-routed webhooks 401'd. The secret existed — in a `.env` file forty
+  feet away, under a different key name.
+- Retries were **not deduplicated**, so anything that did get through would double-count.
+
+Any monitoring you would plausibly have — endpoint uptime, error rate, latency — was green
+throughout. The endpoint was *up*. Nothing ever asked it to do anything.
+
+**The fix is an order of operations**, in `kit/webhook_rail.py`:
+
+```
+verify -> parse -> dedupe -> record -> fulfil
+```
+
+Fulfilment runs **last**, and its failure does not roll back the recording:
+
+> A sale you recorded but failed to deliver is a support ticket.
+> A sale you delivered but failed to record is a hole in your books that nothing will surface.
+
+Three rules inside `verify()` that are each easy to get wrong:
+
+- Verify the **raw bytes**, never a re-serialised dict. `json.loads` then `json.dumps`
+  reorders keys and changes whitespace; the signature will never match again.
+- An **empty secret returns False**. It must never mean "skip the check" — an internet-facing
+  revenue route that mints on an unverified call is a free-money endpoint for whoever finds it.
+- Compare with `hmac.compare_digest`, not `==`, so you do not leak the expected digest
+  one byte at a time.
+
+**Test-mode money must never be income.** `Event.live` is the most important field on the
+struct. Processor test orders, sandbox checkouts and your own smoke tests have to land in a
+separate ledger. Mine did not, once: a hand-fired test webhook put **$98.99** into the
+briefings, the P&L and the fitness function that decided what to build next. The system spent
+weeks optimising toward a number that was a rehearsal.
+
+**How to verify yours actually works — do this today:**
+
+```bash
+# 1. bad signature must be rejected
+curl -s -o /dev/null -w "%{http_code}\n" -X POST https://your-host/webhook/provider \
+  -H "X-Signature: deadbeef" --data-binary @payload.json     # expect 401
+
+# 2. good signature must record exactly one row
+#    (compute the HMAC over the exact bytes you send)
+```
+
+Then check your processor's webhook list for `last_sent_at`. If it is null, your rail has
+never run, regardless of how good the handler code is.
+
+> **Trap I lost an hour to:** if your endpoint is behind Cloudflare, it may return **403 error
+> 1010** to `Python-urllib` while accepting browsers and your processor perfectly well. Test
+> with a realistic `User-Agent` or you will debug a rail that was fine.
+
+---
+
+## The other four
+
+Same shape, all of them: the system reported success and produced nothing.
+
+- **The gate that fails closed and deadlocks everything** — why "the user said no" and "I could
+  not ask the user" must be different verdicts, and what happens for months when they aren't.
+- **The loop that ran for three weeks and produced nothing** — health checks answer *did it
+  run?*. The question that matters is *did running it change anything?*
+- **The tunable that was secretly an off-switch** — one number quietly starved a third of the
+  system, and no error was ever raised.
+- **Delivering the sales page to the person who just bought it** — the fulfilment bug that is
+  invisible until someone has actually paid you.
+
+The code for all four is in this package, free, above. The full write-ups — the specific
+diagnoses, the numbers each was caught by, and the method that found them — are the paid
+post-mortem:
+
+**→ [Get the full post-mortem](https://get-agents-kit.com/agents-kit/)**
+
+That is the part that isn't reproducible from the code: what the symptom looked like, every
+wrong theory ruled out first, and the one measurement that finally showed what was happening.
+
+---
+
+## Licence
+
+Code (`agents_kit/`, `tests/`): **MIT** — copy it, ship it, sell what you build with it.
+The written post-mortem is sold separately and is not MIT; see `LICENSE-POSTMORTEM.txt`.

agents_toolkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agents_kit/__init__.py,sha256=bbnzrYdtp4uwXIO9aHxkDRlM0Iw8iBziY-cUc9Lo07I,703
+agents_kit/attention.py,sha256=1xojj-pvg6nH3buZHLs7GaVb4NCwTJEhbLBZ8_mSqzM,4305
+agents_kit/delivery.py,sha256=-UgToj_krvtiat3UM09fUZake7LGXW2nbBhKxpfCdNg,4372
+agents_kit/gates.py,sha256=jwrTDotGEaznRqIE3MKNBSCgf6Sy8eg3QOMAMVuOc0M,3593
+agents_kit/staleness.py,sha256=Jg5knqUOxRjQcMifT1pn7zcSM3_0C4Zary5rfQAqJ5M,3104
+agents_kit/webhook_rail.py,sha256=RBgjihw5rR8s5CKJnvNUut2l4P_1GSnlCuNFDkIjNsw,5636
+agents_toolkit-1.0.0.dist-info/METADATA,sha256=DuPfYTHj4gll1Kzg2LmShDXCdhZefof-OiLsNkr5Foc,8703
+agents_toolkit-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agents_toolkit-1.0.0.dist-info/licenses/LICENSE,sha256=gX1Kb980mRrtcqnhgahXMFy6WE6780XD_FaXNI6gt9E,1324
+agents_toolkit-1.0.0.dist-info/licenses/LICENSE-POSTMORTEM.txt,sha256=0faB3EAoaq76G8zoEC-kEdQJ9Ul1zhGdFbTlxgKQrjs,584
+agents_toolkit-1.0.0.dist-info/RECORD,,

agents_toolkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agents_toolkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Mribai
+
+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.
+
+---
+
+This MIT licence covers the CODE in agents_kit/ and tests/ only.
+
+The written post-mortem sold separately (POSTMORTEM.md and the incident
+analysis it contains) is not covered by this licence and may not be
+redistributed. See LICENSE-POSTMORTEM.txt.

agents_toolkit-1.0.0.dist-info/licenses/LICENSE-POSTMORTEM.txt

@@ -0,0 +1,13 @@
+Agents Kit — post-mortem licence (the written incident analysis, sold separately).
+
+You may read it, quote it with attribution, and apply everything in it to your own
+systems, commercial or not.
+
+You may not redistribute or resell the post-mortem itself, in whole or in
+substantial part.
+
+The CODE in agents_kit/ is separately licensed under the MIT licence (see LICENSE)
+and carries no such restriction — copy it freely.
+
+No warranty. It is extracted from a production system and tested, but your money rail
+is your responsibility — verify it end to end before you rely on it.