trodo-python 2.23.3__tar.gz → 2.24.0__tar.gz

{trodo_python-2.23.3 → trodo_python-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trodo-python
-Version: 2.23.3
+Version: 2.24.0
 Summary: Trodo Analytics SDK for Python — server-side event tracking
 License: ISC
 Keywords: analytics,tracking,trodo,server-side

{trodo_python-2.23.3 → trodo_python-2.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trodo-python"
-version = "2.23.3"
+version = "2.24.0"
 description = "Trodo Analytics SDK for Python — server-side event tracking"
 readme = "README.md"
 license = { text = "ISC" }

trodo_python-2.24.0/tests/test_sender.py

@@ -0,0 +1,273 @@
+"""Background delivery (2.24): the agent's caller never waits on Trodo, and a
+trace is lost only when the queue is full, the server rejects it, or ten
+minutes of retrying did not get it accepted.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+import pytest
+
+from trodo.delivery.sender import Sender, detect_mode, parse_retry_after_s
+from trodo.otel.processor import TrodoSpanProcessor
+from trodo.otel.wrap_agent import wrap_agent
+
+
+class Server:
+    """A fake /api/sdk/batch: a scripted list of replies, then 200 for everything."""
+
+    def __init__(self, script: Optional[List[Any]] = None, delay_s: float = 0.0) -> None:
+        self.script = list(script or [])
+        self.posts: List[Dict[str, Any]] = []
+        self.delay_s = delay_s
+        self.lock = threading.Lock()
+
+    def post_raw(self, path: str, body: Dict[str, Any], timeout: float = 0, gzip_body: bool = True):
+        if self.delay_s:
+            time.sleep(self.delay_s)
+        with self.lock:
+            self.posts.append({"path": path, "body": body, "at": time.time()})
+            nxt = self.script.pop(0) if self.script else None
+        if isinstance(nxt, Exception):
+            raise nxt
+        if nxt is not None:
+            return nxt
+        return 200, None, {"results": [{"status": 200} for _ in body["items"]]}
+
+    def post_run_ingest(self, p):
+        self.posts.append({"path": "legacy", "body": {"items": [p]}})
+        return {}
+
+
+def run(rid: str) -> Dict[str, Any]:
+    return {"run": {"run_id": rid, "agent_name": "bot"}, "spans": [{"span_id": f"{rid}-s1"}]}
+
+
+def fast(**o: Any) -> Dict[str, Any]:
+    """Sender options that make a test run in well under a second."""
+    return {"mode": "background", "on_error": lambda e: None, "register_atexit": False, "flush_interval_s": 0.05, **o}
+
+
+def wait_for(cond, timeout=3.0):
+    end = time.time() + timeout
+    while time.time() < end:
+        if cond():
+            return True
+        time.sleep(0.01)
+    return cond()
+
+
+def test_enqueue_returns_at_once_and_the_batch_follows():
+    s = Server(delay_s=0.2)
+    sender = Sender(s, **fast())
+    t0 = time.time()
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert time.time() - t0 < 0.05
+    assert s.posts == []
+    assert wait_for(lambda: len(s.posts) == 1)
+    assert s.posts[0]["path"] == "/api/sdk/batch"
+    assert s.posts[0]["body"]["items"] == [run("a"), run("b")]
+    sender.flush()
+    assert sender.stats()["sent"] == 2 and sender.stats()["dropped"] == 0
+
+
+def test_flush_at_items_sends_without_waiting_for_the_interval():
+    s = Server()
+    sender = Sender(s, **fast(flush_interval_s=60.0, flush_at=5))
+    for i in range(5):
+        sender.enqueue(run(f"r{i}"))
+    assert wait_for(lambda: len(s.posts) == 1)
+    assert len(s.posts[0]["body"]["items"]) == 5
+
+
+def test_429_pauses_the_sender_and_loses_nothing():
+    s = Server([(429, "0.3", {"error": "Rate ceiling exceeded"})])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: len(s.posts) == 1)
+    sender.enqueue(run("b"))
+    time.sleep(0.15)
+    assert len(s.posts) == 1          # still paused
+    assert sender.stats()["paused_until"] > time.time() - 0.01
+    assert wait_for(lambda: len(s.posts) == 2)
+    assert s.posts[1]["body"]["items"] == [run("a"), run("b")]
+    sender.flush()
+    assert sender.stats()["sent"] == 2 and sender.stats()["dropped"] == 0
+
+
+def test_outage_is_retried_with_backoff_until_the_server_is_back(monkeypatch):
+    import trodo.delivery.sender as m
+    monkeypatch.setattr(m, "_MIN_BACKOFF_S", 0.02)
+    s = Server([(503, None, None), RuntimeError("ECONNRESET"), RuntimeError("timeout")])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: sender.stats()["sent"] == 1, timeout=5)
+    assert len(s.posts) == 4
+    assert sender.stats()["dropped"] == 0
+
+
+def test_per_item_verdicts_accepted_rejected_deferred():
+    s = Server([(200, None, {"results": [{"status": 200}, {"status": 400, "error": "bad run"}, {"status": 429, "deferred": True}], "retry_after_ms": 100})])
+    sender = Sender(s, **fast(flush_at=3))
+    for rid in ("ok", "bad", "late"):
+        sender.enqueue(run(rid))
+    assert wait_for(lambda: len(s.posts) == 2)
+    assert s.posts[1]["body"]["items"] == [run("late")]
+    assert s.posts[1]["body"]["dropped"] == {"count": 1, "by_reason": {"rejected": 1}}   # the server is told
+    sender.flush()
+    st = sender.stats()
+    assert st["sent"] == 2 and st["dropped_by_reason"] == {"rejected": 1}
+
+
+def test_413_splits_the_batch_and_a_single_oversized_item_is_dropped():
+    s = Server([(413, None, {"error": "too large"}), (413, None, None)])
+    sender = Sender(s, **fast(flush_at=2))
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert wait_for(lambda: sender.stats()["sent"] == 1 and sender.stats()["dropped"] == 1)
+    assert [len(p["body"]["items"]) for p in s.posts] == [2, 1, 1]
+    assert sender.stats()["dropped_by_reason"] == {"too_large": 1}
+
+
+def test_a_full_queue_drops_the_oldest_and_counts_it():
+    s = Server([RuntimeError("down")])
+    sender = Sender(s, **fast(flush_interval_s=60.0, max_queue_items=3))
+    for rid in "abcde":
+        sender.enqueue(run(rid))
+    st = sender.stats()
+    assert st["queued"] == 3 and st["dropped_by_reason"] == {"queue_full": 2}
+    sender.flush(timeout_s=2)
+    sent = [i["run"]["run_id"] for p in s.posts for i in p["body"]["items"]]
+    assert sent[-3:] == ["c", "d", "e"]   # the newest survived
+
+
+def test_gives_up_after_max_retry(monkeypatch):
+    import trodo.delivery.sender as m
+    monkeypatch.setattr(m, "_MIN_BACKOFF_S", 0.01)
+    monkeypatch.setattr(m, "_MAX_BACKOFF_S", 0.02)
+    s = Server([RuntimeError("down")] * 100)
+    sender = Sender(s, **fast(max_retry_s=0.2))
+    sender.enqueue(run("a"))
+    assert wait_for(lambda: sender.stats()["dropped"] == 1, timeout=5)
+    assert sender.stats()["dropped_by_reason"] == {"gave_up": 1}
+    assert sender.stats()["queued"] == 0
+
+
+def test_shutdown_flushes_then_stops_accepting():
+    s = Server()
+    sender = Sender(s, **fast(flush_interval_s=60.0))
+    sender.enqueue(run("a"))
+    sender.shutdown()
+    assert sender.stats()["sent"] == 1
+    sender.enqueue(run("b"))
+    time.sleep(0.1)
+    assert len(s.posts) == 1
+
+
+def test_legacy_server_without_batch_route_keeps_refused_items():
+    s = Server([(404, None, {"error": "Not found"}), (200, None, {"success": True}), (503, None, None)])
+    sender = Sender(s, **fast())
+    sender.enqueue(run("a")); sender.enqueue({"run_id": "a", "feedback": {"rating": 5}})
+    assert wait_for(lambda: sender.stats()["sent"] == 2, timeout=5)
+    assert [p["path"] for p in s.posts][:3] == ["/api/sdk/batch", "/api/sdk/runs/ingest", "/api/sdk/runs/a/feedback"]
+    assert sender.stats()["dropped"] == 0
+
+
+def test_on_error_sees_drops():
+    seen: List[str] = []
+    sender = Sender(Server(), mode="background", on_error=lambda e: seen.append(str(e)), register_atexit=False, max_queue_items=1)
+    sender.enqueue(run("a")); sender.enqueue(run("b"))
+    assert len(seen) == 1 and "queue is full" in seen[0]
+
+
+def test_immediate_mode_blocks_only_within_its_budget():
+    s = Server([(503, None, None)] * 50)
+    slept: List[float] = []
+    clock = [0.0]
+
+    def sleep(x):
+        slept.append(x); clock[0] += x
+
+    sender = Sender(s, mode="immediate", on_error=lambda e: None, immediate_retry_s=15.0, now=lambda: clock[0], sleep=sleep)
+    sender.enqueue(run("a"))
+    assert sender.stats()["dropped_by_reason"] == {"gave_up": 1}
+    assert sum(slept) <= 15.0
+
+
+def test_immediate_mode_sends_before_returning():
+    s = Server([RuntimeError("blip")])
+    sender = Sender(s, mode="immediate", on_error=lambda e: None, sleep=lambda x: None)
+    sender.enqueue(run("a"))
+    assert len(s.posts) == 2 and sender.stats()["sent"] == 1
+
+
+def test_auto_mode_detection():
+    assert detect_mode({}) == "background"
+    assert detect_mode({"AWS_LAMBDA_FUNCTION_NAME": "fn"}) == "immediate"
+    assert detect_mode({"K_SERVICE": "svc"}) == "immediate"
+    assert detect_mode({"VERCEL": "1"}) == "immediate"
+    assert detect_mode({"KUBERNETES_SERVICE_HOST": "10.0.0.1"}) == "background"
+    assert parse_retry_after_s("12", 0) == 12.0
+    assert parse_retry_after_s("soon", 0) is None
+
+
+# ── through wrap_agent ───────────────────────────────────────────────────────
+
+def test_wrap_agent_returns_before_the_send_and_the_run_arrives_whole():
+    s = Server(delay_s=0.3)
+    sender = Sender(s, **fast())
+    processor = TrodoSpanProcessor(http_client=s, sender=sender)
+    t0 = time.time()
+    with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat", distinct_id="u") as r:
+        r.set_input({"q": "hello"}); r.set_output({"a": "world"})
+    assert time.time() - t0 < 0.1     # not the server's 300 ms
+    sender.flush()
+    item = s.posts[0]["body"]["items"][0]
+    assert item["run"]["agent_name"] == "chat" and item["run"]["output"] == {"a": "world"}
+
+
+def test_async_with_wrap_agent_does_not_block_the_event_loop():
+    s = Server(delay_s=0.3)
+    sender = Sender(s, **fast())
+    processor = TrodoSpanProcessor(http_client=s, sender=sender)
+
+    async def main():
+        ticks = 0
+
+        async def ticker():
+            nonlocal ticks
+            for _ in range(5):
+                await asyncio.sleep(0.01); ticks += 1
+
+        t = asyncio.create_task(ticker())
+        async with wrap_agent(processor=processor, team_site_id="site-x", agent_name="chat") as r:
+            await asyncio.sleep(0.02)
+            r.set_output("done")
+        await t
+        return ticks
+
+    assert asyncio.run(main()) == 5
+    sender.flush()
+    assert s.posts[0]["body"]["items"][0]["run"]["output"] == "done"
+
+
+def test_agent_decorator_on_an_async_function_records_the_awaited_result():
+    from trodo.client import TrodoClient
+
+    s = Server()
+    client = TrodoClient(site_id="site-x", auto_instrument=False, delivery="background", delivery_options={"flush_interval_s": 0.05})
+    client._sender._http = s   # the fake server behind the real sender
+    client._sender._o["flush_interval_s"] = 0.05
+
+    @client.agent("async-bot")
+    async def bot(q: str) -> str:
+        await asyncio.sleep(0.01)
+        return q.upper()
+
+    assert asyncio.run(bot("hi")) == "HI"
+    client.flush(timeout=2)
+    item = s.posts[0]["body"]["items"][0]
+    assert item["run"]["agent_name"] == "async-bot"
+    assert item["run"]["output"] == "HI"     # not "<coroutine object ...>"

{trodo_python-2.23.3 → trodo_python-2.24.0}/trodo/__init__.py

@@ -41,7 +41,7 @@ Downstream microservice (join the caller's run instead of making a new one):
 
 from __future__ import annotations
 
-__version__ = "2.21.0"
+__version__ = "2.24.0"
 
 from typing import Any, Callable, Dict, List, Optional, Union
 
@@ -163,6 +163,8 @@ def init(
     auto_instrument: bool = True,
     disable_instrumentations: Optional[List[str]] = None,
     otel_mode: str = "trodo",
+    delivery: str = "auto",
+    delivery_options: Optional[Dict[str, Any]] = None,
 ) -> TrodoClient:
     """Initialise the singleton SDK instance.
 
@@ -171,6 +173,19 @@ def init(
     any other installed opentelemetry-instrumentation-* package, so
     LLM calls emit token/cost spans with no further code.
 
+    ``delivery`` (2.24): how traces reach Trodo.
+      'background' — wrap_agent returns at once; a daemon thread posts queued
+                     runs in batches every second, retries while nobody waits,
+                     and flushes at exit. The default on servers.
+      'immediate'  — the run is sent before wrap_agent returns, with short
+                     retries (≤ 15 s), for platforms that freeze between
+                     requests: Lambda, Cloud Functions, Cloud Run, Vercel.
+      'auto'       — 'immediate' when such a platform's environment variables
+                     are present, otherwise 'background'. Default.
+    ``delivery_options``: flush_interval_s (1), flush_at (50), max_batch_bytes
+    (4 MB), max_queue_items (10,000), max_queue_bytes (64 MB), max_retry_s
+    (600), exit_flush_s (5).
+
     ``disable_instrumentations`` turns OFF specific instrumentors by id
     (e.g. ``['openai']`` when LangChain is your primary framework, to avoid
     double-counting the same model call). Mirrors Node's
@@ -191,6 +206,8 @@ def init(
         auto_instrument=auto_instrument,
         disable_instrumentations=disable_instrumentations,
         otel_mode=otel_mode,
+        delivery=delivery,
+        delivery_options=delivery_options,
     )
     return _client
 

trodo_python-2.24.0/trodo/_version.py

@@ -0,0 +1 @@
+SDK_VERSION = "2.24.0"

trodo_python-2.24.0/trodo/api/_retry.py

@@ -0,0 +1,30 @@
+"""When to retry a request, and after how long. Mirrors the Node SDK."""
+import random
+from typing import Optional
+
+
+def retry_delay(status: int, retry_after: Optional[str], attempt: int) -> Optional[float]:
+    """Seconds to wait before retrying, or None when not to retry.
+
+    Retries a 5xx, and a 429 that says when (Retry-After): a rate limit is
+    temporary, an exhausted allowance (429 without Retry-After) is not. A
+    server that says Retry-After is honoured (capped at 30 s). Otherwise
+    exponential backoff with jitter, so a burst of clients hit by the same
+    outage does not retry in lockstep and knock it over again.
+    """
+    retryable = status >= 500 or (status == 429 and retry_after is not None)
+    if not retryable:
+        return None
+    try:
+        seconds = float(retry_after) if retry_after is not None else None
+    except ValueError:
+        seconds = None
+    if seconds is not None and seconds >= 0:
+        return min(seconds, 30.0) + random.random()
+    return jittered_backoff(attempt)
+
+
+def jittered_backoff(attempt: int) -> float:
+    """2**attempt seconds, somewhere in its upper half."""
+    base = float(2 ** attempt)
+    return base / 2 + random.random() * (base / 2)

{trodo_python-2.23.3 → trodo_python-2.24.0}/trodo/api/async_client.py

@@ -7,6 +7,7 @@ import asyncio
 from typing import Any, Callable, Dict, Optional
 
 from ..types import ApiResult, EventPayload
+from ._retry import jittered_backoff, retry_delay
 
 
 class AsyncHttpClient:
@@ -51,9 +52,12 @@ class AsyncHttpClient:
         try:
             async with httpx.AsyncClient(timeout=self.timeout) as client:
                 resp = await client.post(url, json=body, headers=headers)
-            if resp.status_code >= 500 and attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s")
+            delay = (
+                retry_delay(resp.status_code, resp.headers.get('retry-after'), attempt)
+                if attempt < self.retries else None
+            )
+            if delay is not None:
+                self._log(f"Retry {attempt + 1} after {delay:.1f}s (status {resp.status_code})")
                 await asyncio.sleep(delay)
                 return await self._request(path, body, attempt + 1)
             try:
@@ -62,7 +66,7 @@ class AsyncHttpClient:
                 return {}
         except Exception as exc:
             if attempt < self.retries:
-                await asyncio.sleep(2 ** attempt)
+                await asyncio.sleep(jittered_backoff(attempt))
                 return await self._request(path, body, attempt + 1)
             self._log(f"Error: {exc}")
             if self.on_error:

{trodo_python-2.23.3 → trodo_python-2.24.0}/trodo/api/endpoints.py

@@ -22,8 +22,11 @@ GROUPS_REMOVE = "/api/sdk/groups/remove_group"
 GROUPS_PROFILE = "/api/sdk/groups/profile"
 # Agent run tracking (Lemma-style, run-centric)
 RUNS_INGEST = "/api/sdk/runs/ingest"
+# Many writes in one request — the background sender (delivery/sender.py).
+BATCH = "/api/sdk/batch"
 RUNS_START = "/api/sdk/runs/start"
 RUNS_BASE = "/api/sdk/runs"  # /runs/{run_id}/end, /spans, /feedback
+SPANS_APPEND = "/api/sdk/spans/append"
 OTLP_TRACES = "/api/sdk/otel/v1/traces"
 # Datasets & experiments
 DATASETS_BASE = "/api/sdk/datasets"  # /datasets/{ref}/items

{trodo_python-2.23.3 → trodo_python-2.24.0}/trodo/api/http_client.py

@@ -10,6 +10,8 @@ import requests
 
 from ..types import ApiResult, EventPayload
 from . import endpoints
+from ._retry import jittered_backoff, retry_delay
+from .._version import SDK_VERSION
 
 
 class HttpClient:
@@ -43,9 +45,12 @@ class HttpClient:
         self._log(f"POST {url}")
         try:
             resp = self._session.post(url, json=body, timeout=self.timeout)
-            if resp.status_code >= 500 and attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s (status {resp.status_code})")
+            delay = (
+                retry_delay(resp.status_code, resp.headers.get('retry-after'), attempt)
+                if attempt < self.retries else None
+            )
+            if delay is not None:
+                self._log(f"Retry {attempt + 1} after {delay:.1f}s (status {resp.status_code})")
                 time.sleep(delay)
                 return self._request(path, body, attempt + 1)
             if resp.status_code >= 400:
@@ -72,15 +77,46 @@ class HttpClient:
                 return {}
         except Exception as exc:
             if attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s (network error)")
+                delay = jittered_backoff(attempt)
+                self._log(f"Retry {attempt + 1} after {delay:.1f}s (network error)")
                 time.sleep(delay)
                 return self._request(path, body, attempt + 1)
             self._log(f"Error: {exc}")
             if self.on_error:
-                self.on_error(exc)
+                try:
+                    self.on_error(exc)
+                except Exception:
+                    pass  # a handler that raises must not surface into user code
             return {}
 
+    def post_raw(
+        self, path: str, body: Dict[str, Any], timeout: Optional[float] = None, gzip_body: bool = True,
+    ) -> tuple:
+        """One attempt, the status told: ``(status, retry_after, parsed_body)``.
+
+        The background sender (delivery/sender.py) decides what to do with a
+        429, a 5xx or a timeout, so unlike ``_request`` this neither retries
+        nor swallows: it raises only on a network error or a timeout. Bodies
+        over 8 KB are gzipped.
+        """
+        import gzip as _gzip
+        import json as _json
+
+        url = f"{self.api_base}{path}"
+        raw = _json.dumps(body, default=str).encode("utf-8")
+        headers: Dict[str, str] = {"User-Agent": f"trodo-python/{SDK_VERSION}"}
+        data = raw
+        if gzip_body and len(raw) > 8 * 1024:
+            data = _gzip.compress(raw)
+            headers["Content-Encoding"] = "gzip"
+        self._log(f"POST {url} ({len(raw)} bytes{', gzip' if 'Content-Encoding' in headers else ''})")
+        resp = self._session.post(url, data=data, headers=headers, timeout=timeout or self.timeout)
+        try:
+            parsed = resp.json() if resp.text else None
+        except Exception:
+            parsed = {"body": resp.text[:300]}
+        return resp.status_code, resp.headers.get("retry-after"), parsed
+
     def _get(
         self, path: str, params: Optional[Dict[str, Any]] = None, attempt: int = 0
     ) -> ApiResult:
@@ -91,9 +127,12 @@ class HttpClient:
         self._log(f"GET {url}")
         try:
             resp = self._session.get(url, params=params or {}, timeout=self.timeout)
-            if resp.status_code >= 500 and attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s (status {resp.status_code})")
+            delay = (
+                retry_delay(resp.status_code, resp.headers.get('retry-after'), attempt)
+                if attempt < self.retries else None
+            )
+            if delay is not None:
+                self._log(f"Retry {attempt + 1} after {delay:.1f}s (status {resp.status_code})")
                 time.sleep(delay)
                 return self._get(path, params, attempt + 1)
             try:
@@ -108,8 +147,8 @@ class HttpClient:
             return data
         except Exception as exc:
             if attempt < self.retries:
-                delay = 2 ** attempt
-                self._log(f"Retry {attempt + 1} after {delay}s (network error)")
+                delay = jittered_backoff(attempt)
+                self._log(f"Retry {attempt + 1} after {delay:.1f}s (network error)")
                 time.sleep(delay)
                 return self._get(path, params, attempt + 1)
             self._log(f"Error: {exc}")

{trodo_python-2.23.3 → trodo_python-2.24.0}/trodo/client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import functools
+import inspect
 from typing import Any, Callable, Dict, List, Optional, Union
 
 from .api.http_client import HttpClient
@@ -14,6 +15,7 @@ from .queue.batch_flusher import BatchFlusher
 from .auto.auto_event_manager import AutoEventManager
 from .user_context import UserContext
 from .otel.processor import TrodoSpanProcessor
+from .delivery.sender import Sender
 from .otel.wrap_agent import (
     wrap_agent as wrap_agent_ctx,
     span as span_ctx,
@@ -61,6 +63,8 @@ class TrodoClient:
         disable_instrumentations: Optional[List[str]] = None,
         otel_mode: str = "trodo",
         max_cached_users: int = 10_000,
+        delivery: str = "auto",
+        delivery_options: Optional[Dict[str, Any]] = None,
     ) -> None:
         if not site_id:
             raise ValueError("trodo-python: site_id is required")
@@ -105,7 +109,11 @@ class TrodoClient:
         # API server. An evicted user is simply rebuilt on next use.
         self._user_context_cache: LruDict[str, UserContext] = LruDict(max_cached_users)
 
-        self._span_processor = TrodoSpanProcessor(http_client=self._http)
+        # Background delivery (2.24): runs and spans are queued and sent by a
+        # daemon thread; 'immediate' on serverless platforms (detected from
+        # the environment when delivery='auto').
+        self._sender = Sender(self._http, mode=delivery, on_error=on_error, debug=debug, **(delivery_options or {}))
+        self._span_processor = TrodoSpanProcessor(http_client=self._http, sender=self._sender)
         if auto_instrument:
             import os
             if os.environ.get("TRODO_LEGACY_INIT") == "1":
@@ -299,10 +307,12 @@ class TrodoClient:
     # Lifecycle
     # --------------------------------------------------------------------------
 
-    def flush(self) -> None:
+    def flush(self, timeout: Optional[float] = None) -> None:
+        """Send everything queued and wait for it (bounded by ``timeout`` seconds, if given)."""
         if self._batch_flusher:
             self._batch_flusher.flush()
         self._span_processor.force_flush()
+        self._sender.flush(timeout)
         # 'otlp' mode: drain the OTel BatchSpanProcessor too — it batches for
         # up to 5s, so without this a short-lived process drops its spans.
         _flush_otlp_pipeline()
@@ -313,8 +323,13 @@ class TrodoClient:
             self._batch_flusher.stop()
             self._batch_flusher.flush()
         self._span_processor.shutdown()
+        self._sender.shutdown()
         _shutdown_otlp_pipeline()
 
+    def delivery_stats(self) -> Dict[str, Any]:
+        """What the background sender is doing: queued, in flight, sent, dropped (by reason), paused-until, mode."""
+        return self._sender.stats()
+
     # --------------------------------------------------------------------------
     # Agent Runs — Lemma-style seamless wrapping
     # --------------------------------------------------------------------------
@@ -364,16 +379,31 @@ class TrodoClient:
         """Decorator form of wrap_agent."""
 
         def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
-            @functools.wraps(fn)
-            def wrapper(*args: Any, **kwargs: Any) -> Any:
-                with self.wrap_agent(
+            def _run():
+                return self.wrap_agent(
                     agent_name,
                     distinct_id=distinct_id,
                     conversation_id=conversation_id,
                     parent_run_id=parent_run_id,
                     metadata=metadata,
                     user=user,
-                ) as run:
+                )
+
+            if inspect.iscoroutinefunction(fn):
+                # An ``async def`` agent (2.24). Before, the run closed the
+                # moment the coroutine was created and recorded the coroutine
+                # object as its output.
+                @functools.wraps(fn)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    async with _run() as run:
+                        result = await fn(*args, **kwargs)
+                        run.set_output(result)
+                        return result
+                return async_wrapper
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _run() as run:
                     result = fn(*args, **kwargs)
                     run.set_output(result)
                     return result
@@ -600,7 +630,10 @@ class TrodoClient:
             "distinct_id": distinct_id,
             "attributes": metadata or {},
         }
-        return self._http.post_run_feedback(run_id, payload)
+        # Queued behind the run it belongs to (2.24): never waits on the
+        # network, survives an outage, and lands after its run.
+        self._sender.enqueue({"run_id": run_id, "feedback": payload})
+        return {}
 
     def feedback_props(self, run_id: str, props: FeedbackProps) -> ApiResult:
         """Convenience — pass a FeedbackProps dataclass."""