agents-toolkit 1.0.0__tar.gz

agents_toolkit-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

agents_toolkit-1.0.0/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/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.

agents_toolkit-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,133 @@
+# 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/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_toolkit-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_toolkit-1.0.0/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_toolkit-1.0.0/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_toolkit-1.0.0/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_toolkit-1.0.0/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/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agents-toolkit"
+version = "1.0.0"
+description = "Five things an autonomous agent gets wrong silently, and the code that stops each one. Dependency-free stdlib."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Ahmed Mribai", email = "hello@get-agents-kit.com" }]
+keywords = [
+    "agents", "llm", "autonomous", "webhook", "idempotency",
+    "reliability", "observability", "fulfilment", "quality-gates",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# Deliberately empty, and it is the selling point: every module is standard library only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://get-agents-kit.com/agents-kit/"
+# Source deliberately omitted until the public repo exists — a 404 on the PyPI
+# sidebar reads worse than no link at all.
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agents_kit"]
+
+[tool.hatch.build.targets.sdist]
+# The post-mortem is sold separately — it must never ride along in a published artifact.
+exclude = ["POSTMORTEM.md", "dist/", ".pytest_cache/", "__pycache__/"]

agents_toolkit-1.0.0/tests/test_kit.py

@@ -0,0 +1,290 @@
+"""Every claim the kit makes, as an executable test.
+
+These are the regression tests for the production incidents the kit exists to prevent.
+If you change a module, these must stay green.
+"""
+
+import hashlib
+import hmac
+import json
+import time
+
+from agents_kit import attention, delivery, gates, staleness, webhook_rail
+
+SECRET = "test-signing-secret"
+
+
+def _signed(payload: dict) -> tuple[bytes, str]:
+    raw = json.dumps(payload).encode()
+    sig = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
+    return raw, sig
+
+
+def _order(oid="ord_1", total=9899, test_mode=False, email="buyer@example.com"):
+    return {"meta": {"custom_data": {"reference": "42"}},
+            "data": {"id": oid, "attributes": {"total": total, "test_mode": test_mode,
+                                               "user_email": email, "currency": "USD"}}}
+
+
+class FakeLedger:
+    def __init__(self):
+        self.rows = {}
+
+    def seen(self, event_id):
+        return event_id in self.rows
+
+    def record(self, event_id, amount, currency, live):
+        self.rows[event_id] = {"amount": amount, "currency": currency, "live": live}
+
+
+# -- webhook rail -------------------------------------------------------------
+
+def test_bad_signature_is_rejected():
+    raw, _ = _signed(_order())
+    status, _ = webhook_rail.handle(raw, "deadbeef", "order_created", SECRET,
+                                    FakeLedger(), lambda e: None)
+    assert status == 401
+
+
+def test_empty_secret_never_passes():
+    """An unset secret must not mean 'skip verification'."""
+    raw, sig = _signed(_order())
+    assert webhook_rail.verify(raw, sig, "") is False
+    status, _ = webhook_rail.handle(raw, sig, "order_created", "", FakeLedger(), lambda e: None)
+    assert status == 401
+
+
+def test_good_signature_records_once():
+    raw, sig = _signed(_order())
+    ledger = FakeLedger()
+    status, body = webhook_rail.handle(raw, sig, "order_created", SECRET, ledger, lambda e: None)
+    assert status == 200 and body["recorded"] == 98.99
+    assert ledger.rows["ord_1"]["live"] is True
+
+
+def test_retry_does_not_double_count():
+    raw, sig = _signed(_order())
+    ledger = FakeLedger()
+    webhook_rail.handle(raw, sig, "order_created", SECRET, ledger, lambda e: None)
+    status, body = webhook_rail.handle(raw, sig, "order_created", SECRET, ledger, lambda e: None)
+    assert status == 200 and body["status"] == "duplicate"
+    assert len(ledger.rows) == 1
+
+
+def test_test_mode_is_not_live_revenue():
+    """The rehearsal must never be reportable as income."""
+    raw, sig = _signed(_order(test_mode=True))
+    ledger = FakeLedger()
+    webhook_rail.handle(raw, sig, "order_created", SECRET, ledger, lambda e: None)
+    assert ledger.rows["ord_1"]["live"] is False
+
+
+def test_refund_books_negative():
+    raw, sig = _signed(_order(oid="ord_r"))
+    ledger = FakeLedger()
+    webhook_rail.handle(raw, sig, "order_refunded", SECRET, ledger, lambda e: None)
+    assert ledger.rows["ord_r"]["amount"] == -98.99
+
+
+def test_fulfilment_failure_still_records_the_sale():
+    def boom(_event):
+        raise RuntimeError("mail server down")
+
+    raw, sig = _signed(_order())
+    ledger = FakeLedger()
+    status, body = webhook_rail.handle(raw, sig, "order_created", SECRET, ledger, boom)
+    assert status == 200 and "pending" in body["fulfilment"]
+    assert ledger.rows["ord_1"]["amount"] == 98.99      # the money is still on the books
+
+
+def test_malformed_body_is_400_not_a_crash():
+    sig = hmac.new(SECRET.encode(), b"not json", hashlib.sha256).hexdigest()
+    status, _ = webhook_rail.handle(b"not json", sig, "order_created", SECRET,
+                                    FakeLedger(), lambda e: None)
+    assert status == 400
+
+
+# -- gates --------------------------------------------------------------------
+
+def _judge(ok=True, error=False):
+    return lambda: gates.Judgement(ok=ok, error=error)
+
+
+def test_gate_blocks_a_measured_low_score():
+    r = gates.evaluate([_judge(ok=False)] * 4, threshold=0.5)
+    assert r.verdict is gates.Verdict.BLOCK and r.allowed is False
+
+
+def test_gate_passes_a_measured_high_score():
+    r = gates.evaluate([_judge(ok=True)] * 4, threshold=0.5)
+    assert r.verdict is gates.Verdict.PASS and r.allowed is True
+
+
+def test_gate_returns_unknown_when_every_judge_errors():
+    """THE regression: an LLM outage must not read as unanimous rejection."""
+    r = gates.evaluate([_judge(error=True)] * 5, threshold=0.5)
+    assert r.verdict is gates.Verdict.UNKNOWN
+    assert r.allowed is True            # unknown passes through
+    assert r.errors == 5 and r.judged == 0
+
+
+def test_gate_unknown_when_a_judge_raises():
+    def raising():
+        raise TimeoutError("429 rate limited")
+
+    r = gates.evaluate([raising] * 3, threshold=0.5)
+    assert r.verdict is gates.Verdict.UNKNOWN and r.allowed is True
+
+
+def test_partial_errors_still_score_on_what_was_measured():
+    r = gates.evaluate([_judge(ok=True), _judge(ok=True), _judge(error=True)], threshold=0.5)
+    assert r.judged == 2 and r.errors == 1
+    assert r.score == 1.0 and r.verdict is gates.Verdict.PASS
+
+
+def test_measure_only_mode_never_blocks():
+    r = gates.evaluate([_judge(ok=False)] * 4, threshold=0.5, enabled=False)
+    assert r.verdict is gates.Verdict.PASS and r.score == 0.0
+
+
+# -- staleness ----------------------------------------------------------------
+
+def test_zero_output_streak_is_detected():
+    m = staleness.StalenessMonitor(patience=3)
+    for _ in range(2):
+        assert m.record("discovery", produced=0) is False
+    assert m.record("discovery", produced=0) is True
+    assert m.stale() == ["discovery"]
+
+
+def test_output_resets_the_streak():
+    m = staleness.StalenessMonitor(patience=2)
+    m.record("perception", 0)
+    m.record("perception", 5)
+    assert m.stale() == []
+
+
+def test_productive_task_never_flagged():
+    m = staleness.StalenessMonitor(patience=2)
+    for _ in range(10):
+        m.record("publisher", produced=3)
+    assert m.stale() == [] and m.report()[0]["total_output"] == 30
+
+
+def test_report_ranks_worst_first():
+    m = staleness.StalenessMonitor(patience=2)
+    for _ in range(4):
+        m.record("dead", 0)
+    m.record("alive", 1)
+    assert m.report()[0]["task"] == "dead" and m.report()[0]["stale"] is True
+
+
+# -- attention ----------------------------------------------------------------
+
+def test_expensive_bid_is_reported_as_starving():
+    """THE regression: a bid that can never win must be visible, not silently dead."""
+    a = attention.Arbiter(budget=3.0)
+    bids = [attention.Bid("cheap", lambda: 1, cost=0.3),
+            attention.Bid("expensive", lambda: 1, cost=5.0)]
+    for _ in range(5):
+        a.run(bids)
+    assert "expensive" in a.starving()
+
+
+def test_feasibility_check_flags_an_unaffordable_bid():
+    a = attention.Arbiter(budget=3.0)
+    bids = [attention.Bid("a", lambda: 1, cost=1.0), attention.Bid("b", lambda: 1, cost=4.0)]
+    f = a.feasible(bids)
+    assert f["never_affordable"] == ["b"] and f["total_cost"] == 5.0
+
+
+def test_budget_is_respected():
+    a = attention.Arbiter(budget=1.0)
+    bids = [attention.Bid("b%d" % i, lambda: 1, cost=0.4) for i in range(5)]
+    assert len(a.choose(bids)) == 2
+
+
+def test_urgency_lets_a_neglected_bid_eventually_win():
+    a = attention.Arbiter(budget=1.0)
+    fresh = attention.Bid("fresh", lambda: 1, cost=0.5, value=0.9, info=0.9)
+    neglected = attention.Bid("neglected", lambda: 1, cost=0.5, value=0.1, info=0.1)
+    a._last_run["fresh"] = time.time()          # just ran
+    # neglected has never run, so its urgency is 1.0
+    assert "neglected" in [b.name for b in a.choose([fresh, neglected])]
+
+
+def test_a_raising_bid_does_not_kill_the_tick():
+    def boom():
+        raise ValueError("nope")
+
+    a = attention.Arbiter(budget=5.0)
+    out = a.run([attention.Bid("bad", boom, cost=1.0),
+                 attention.Bid("good", lambda: "ok", cost=1.0)])
+    assert out["results"]["good"] == "ok" and "error" in out["results"]["bad"]
+
+
+# -- delivery -----------------------------------------------------------------
+
+class FakeStore:
+    def __init__(self):
+        self.done, self.pending = {}, {}
+
+    def delivered(self, ref):
+        return ref in self.done
+
+    def mark_delivered(self, ref, to, links):
+        self.done[ref] = (to, links)
+
+    def mark_pending(self, ref, to, reason):
+        self.pending[ref] = (to, reason)
+
+
+def test_sales_page_is_never_delivered():
+    """THE regression: the buyer must not be emailed the page they just bought from."""
+    links = delivery.usable_links(
+        ["https://x.com/product/guide.pdf", "https://x.com/sale/index.html"],
+        ["https://x.com/sale/index.html"])
+    assert links == ["https://x.com/product/guide.pdf"]
+
+
+def test_sales_page_directory_twin_is_also_blocked():
+    assert delivery.usable_links(["https://x.com/sale/"], ["https://x.com/sale/index.html"]) == []
+
+
+def test_local_paths_are_never_delivered():
+    assert delivery.usable_links(["file:///C:/Users/me/out.html"], []) == []
+    assert delivery.usable_links(["http://127.0.0.1:8765/x"], []) == []
+
+
+def test_no_usable_link_records_pending_rather_than_sending_junk():
+    store = FakeStore()
+    sent = []
+
+    def send(to, links):
+        sent.append(links)
+        return True
+
+    r = delivery.deliver("ord_1", "b@example.com", ["https://x.com/sale/"],
+                         ["https://x.com/sale/"], store, send)
+    assert r.status == "pending" and not sent
+    assert "ord_1" in store.pending
+
+
+def test_happy_path_delivers_and_is_idempotent():
+    store, sent = FakeStore(), []
+
+    def send(to, links):
+        sent.append(links)
+        return True
+
+    args = ("ord_2", "b@example.com", ["https://x.com/guide.pdf"], ["https://x.com/sale/"])
+    assert delivery.deliver(*args, store, send).status == "delivered"
+    assert delivery.deliver(*args, store, send).status == "duplicate"
+    assert len(sent) == 1
+
+
+def test_failed_send_is_pending_and_retryable():
+    store = FakeStore()
+    r = delivery.deliver("ord_3", "b@example.com", ["https://x.com/g.pdf"], [],
+                         store, lambda to, links: False)
+    assert r.status == "pending" and not store.delivered("ord_3")   # retryable, not sealed