telefi 0.3.0__py3-none-any.whl

telefi/__init__.py

@@ -0,0 +1,9 @@
+"""TeleFi: a Telegram adapter layer for two-way messaging; channels and reply sinks are adapters.
+
+Producers: `from telefi import envelope, publish` (Python) or write an envelope.v1 JSON file
+into the spool's out/ directory (any language). Design: docs/HUB_DESIGN.md. Format: render.py.
+"""
+from telefi.core import drain, envelope, publish, spool_root
+from telefi.render import render_telegram
+
+__all__ = ["drain", "envelope", "publish", "render_telegram", "spool_root"]

telefi/__main__.py

@@ -0,0 +1,127 @@
+"""TeleFi CLI.
+
+    python -m telefi drain                 deliver everything in the spool once (the scheduled task)
+    python -m telefi serve [--interval 30] drain forever; also long-polls Telegram if inbound.enabled
+    python -m telefi preview [type ...]    print each sample exactly as the owner would see it (no send)
+    python -m telefi samples [--send]      route the samples; mock unless --send (then really delivers)
+    python -m telefi validate <file.json>  check an envelope or inbound event against its schema
+    python -m telefi schema <name>         print a published schema (envelope.v1 | inbound.v1 | hub_config.v1)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+import time
+import traceback
+from pathlib import Path
+
+from telefi import core, inbound, schema
+from telefi.render import render_plain
+from telefi.samples import samples
+
+SERVE_RETRY_S = 5
+SERVE_RETRY_MAX_S = 300
+PRUNE_EVERY_S = 3600
+
+
+def _preview(names: list[str], buttons: bool) -> int:
+    for name, env in samples().items():
+        if names and name not in names:
+            continue
+        print(f"===== {name}  (routes to: {', '.join(core.route(env, core.DEFAULT_CONFIG)) or 'nothing'})")
+        print(render_plain(env, buttons=buttons))
+        print()
+    return 0
+
+
+def _samples(send: bool) -> int:
+    cfg = core.load_config()
+    if not send:
+        cfg = {**cfg, "mode": "mock"}
+    with tempfile.TemporaryDirectory() as tmp:
+        spool = Path(tmp) / "spool"
+        for env in samples().values():
+            core.publish(env, spool=spool)
+        for rec in core.drain(cfg, spool=spool):
+            env = rec["envelope"]
+            res = ", ".join(f"{d['channel']}={'ok' if d['ok'] else 'FAILED ' + str(d['error'])}" for d in rec["deliveries"])
+            print(f"{env['source']}.{env['kind']} [{env['severity']}] -> {res or 'no route'}")
+    print("mode:", "LIVE (really sent)" if send else "mock (nothing sent)")
+    return 0
+
+
+def _serve(interval: float) -> int:
+    """Drain + long-poll forever. A failing round is logged to ~/.telefi/hub.log and retried; it
+    never ends the process (the scheduled task would only restart it 5 minutes later)."""
+    cfg = core.load_config()
+    log = core.HOME / "hub.log"
+    core.append_jsonl(log, {"at": core.now_iso(), "event": "serve started", "inbound": cfg.get("inbound", {}).get("enabled")})
+    if cfg.get("inbound", {}).get("enabled"):
+        menu = inbound.register_menu(cfg)
+        core.append_jsonl(log, {"at": core.now_iso(), "event": "command menu", "ok": menu["ok"], "error": menu.get("error")})
+    failures, pruned_at = 0, 0.0
+    while True:
+        try:
+            core.drain(cfg)
+            if time.monotonic() - pruned_at > PRUNE_EVERY_S:
+                core.prune_done(core.spool_root(cfg))
+                pruned_at = time.monotonic()
+            if cfg.get("inbound", {}).get("enabled"):
+                inbound.poll_once(cfg, timeout_s=int(interval))
+            else:
+                time.sleep(interval)
+            failures = 0
+        except Exception:
+            failures += 1
+            wait = min(SERVE_RETRY_S * 2 ** (failures - 1), SERVE_RETRY_MAX_S)   # an outage never spins
+            core.append_jsonl(log, {"at": core.now_iso(), "event": "round failed", "retry_in_s": wait,
+                                    "error": traceback.format_exc()[-2000:]})
+            time.sleep(wait)
+
+
+def main(argv=None) -> int:
+    if sys.stdout is not None:                    # None under pythonw.exe (no console)
+        sys.stdout.reconfigure(encoding="utf-8")   # Windows consoles default to cp1252
+    ap = argparse.ArgumentParser(prog="python -m telefi")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("drain")
+    s = sub.add_parser("serve")
+    s.add_argument("--interval", type=float, default=30.0)
+    p = sub.add_parser("preview")
+    p.add_argument("types", nargs="*")
+    p.add_argument("--no-buttons", action="store_true", help="hide action buttons (as sent while inbound is disabled)")
+    sm = sub.add_parser("samples")
+    sm.add_argument("--send", action="store_true")
+    v = sub.add_parser("validate")
+    v.add_argument("file")
+    sc = sub.add_parser("schema")
+    sc.add_argument("name", choices=schema.SCHEMAS)
+    a = ap.parse_args(argv)
+
+    if a.cmd == "drain":
+        recs = core.drain(core.load_config())
+        failed = [r for r in recs if r.get("rejected") or any(not d["ok"] for d in r["deliveries"])]
+        print(f"[hub] delivered {len(recs) - len(failed)}/{len(recs)}", flush=True)
+        return 1 if failed else 0
+    if a.cmd == "serve":
+        return _serve(a.interval)
+    if a.cmd == "preview":
+        return _preview(a.types, buttons=not a.no_buttons)
+    if a.cmd == "samples":
+        return _samples(a.send)
+    if a.cmd == "validate":
+        obj = json.loads(Path(a.file).read_text(encoding="utf-8"))
+        name = "inbound.v1" if str(obj.get("schema", "")).endswith(".inbound.v1") else "envelope.v1"
+        bad = schema.validate(obj, name)
+        print("\n".join(bad) or f"valid {name}")
+        return 1 if bad else 0
+    if a.cmd == "schema":
+        print(json.dumps(schema.load(a.name), indent=2))
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

telefi/adapters.py

@@ -0,0 +1,95 @@
+"""Outbound channel adapters: `send(envelope, *, buttons) -> {"ok", "error", "message_id"?}`.
+
+A new channel (Slack, SMS, email) is one class here plus one `type` in hub_config.v1.json.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from telefi import logs
+from telefi.render import render_telegram
+
+HTTP_TIMEOUT_S = 10
+TELEGRAM_API = "https://api.telegram.org"
+
+
+def telegram_call(token: str, method: str, body: dict, *, opener: Callable | None = None,
+                  timeout: float = HTTP_TIMEOUT_S) -> dict:
+    """One Bot API call. Returns {"ok", "result"?, "error"?}; never raises, never echoes the URL
+    (it carries the token)."""
+    req = urllib.request.Request(f"{TELEGRAM_API}/bot{token}/{method}", data=json.dumps(body).encode("utf-8"),
+                                 headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with (opener or urllib.request.urlopen)(req, timeout=timeout) as resp:
+            raw = resp.read() if hasattr(resp, "read") else b"{}"
+            data = json.loads(raw or b"{}")
+            if resp.status != 200 or not data.get("ok", True):
+                return {"ok": False, "error": f"HTTP {resp.status}: {str(data.get('description', ''))[:120]}"}
+            return {"ok": True, "result": data.get("result")}
+    except Exception as ex:
+        return {"ok": False, "error": f"{type(ex).__name__}: {getattr(ex, 'code', '')}".strip()}
+
+
+@dataclass
+class MockAdapter:
+    """Records what would be sent; never touches the network. The default in tests and mode=mock."""
+    name: str
+    sent: list = field(default_factory=list)
+    fail: bool = False
+
+    def send(self, env: dict, *, buttons: bool) -> dict:
+        if self.fail:
+            return {"ok": False, "error": "mock failure"}
+        self.sent.append({"envelope_id": env["id"], "rendered": render_telegram(env, buttons=buttons)})
+        return {"ok": True, "error": None, "message_id": len(self.sent)}
+
+
+@dataclass
+class TelegramAdapter:
+    name: str
+    token: str | None
+    chat_id: str | None
+    opener: Callable | None = None
+
+    def send(self, env: dict, *, buttons: bool) -> dict:
+        if not (self.token and self.chat_id):
+            return {"ok": False, "error": "telegram not configured (token/chat env missing)"}
+        r = render_telegram(env, buttons=buttons)
+        body = {"chat_id": self.chat_id, "text": r["text"], "parse_mode": "HTML", "disable_web_page_preview": True}
+        if r["reply_markup"]:
+            body["reply_markup"] = r["reply_markup"]
+        res = telegram_call(self.token, "sendMessage", body, opener=self.opener)
+        return {"ok": res["ok"], "error": res.get("error"),
+                "message_id": (res.get("result") or {}).get("message_id")}
+
+
+@dataclass
+class FileAdapter:
+    name: str
+    path: Path
+
+    def send(self, env: dict, *, buttons: bool) -> dict:
+        logs.append(self.path, {"at": logs.now_iso(), "envelope": env})   # rotates like every record
+        return {"ok": True, "error": None}
+
+
+def telegram_creds(cfg: dict, name: str = "telegram") -> tuple[str | None, str | None]:
+    c = cfg["channels"].get(name, {})
+    return os.environ.get(c.get("token_env", "TELEGRAM_BOT_TOKEN")), os.environ.get(c.get("chat_env", "TELEGRAM_CHAT_ID"))
+
+
+def build_adapters(cfg: dict, *, opener: Callable | None = None, resolve: Callable = lambda raw: Path(os.path.expanduser(raw))) -> dict:
+    out = {}
+    for name, c in cfg["channels"].items():
+        if cfg["mode"] == "mock" or c["type"] == "mock":
+            out[name] = MockAdapter(name)
+        elif c["type"] == "telegram":
+            out[name] = TelegramAdapter(name, *telegram_creds(cfg, name), opener)
+        elif c["type"] == "file":
+            out[name] = FileAdapter(name, resolve(c["path"]))
+    return out

telefi/commands.py

@@ -0,0 +1,63 @@
+"""The command registry: one commands.v1 manifest per app -> /help, /list, the '/' menu, routing.
+
+    /help            every app, every command, usage + one line
+    /help <app>      one app
+    /list            one line per app: its verbs
+    /<app> <verb> x  routed to the app's sink (rewritten to legacy_text for an app's old bare form)
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from telefi import schema
+
+HUB_MANIFEST: dict = {
+    "schema": "telefi.commands.v1", "app": "hub", "summary": "the messaging hub itself", "sink": "hub",
+    "commands": [
+        {"verb": "help", "usage": "/help [app]", "summary": "every command, or one app's"},
+        {"verb": "list", "usage": "/list", "summary": "apps and their commands, one line each"},
+        {"verb": "ack", "usage": "/hub ack", "summary": "stop re-alerts for the latest failure"},
+    ],
+}
+TOP_LEVEL = ("help", "list")             # hub verbs that also work as bare commands
+
+
+def load_manifests(paths: list[str]) -> dict[str, dict]:
+    """app -> manifest, the hub's own first. An invalid manifest raises: a typo must not silently
+    drop an app's commands from /help."""
+    out = {"hub": HUB_MANIFEST}
+    for raw in paths:
+        p = Path(os.path.expanduser(raw))
+        m = json.loads(p.read_text(encoding="utf-8"))
+        bad = schema.validate(m, "commands.v1")
+        if bad:
+            raise ValueError(f"commands manifest {p}: " + "; ".join(bad))
+        out[m["app"]] = m
+    return out
+
+
+def verb(manifests: dict, app: str, name: str) -> dict | None:
+    return next((c for c in manifests.get(app, {}).get("commands", []) if c["verb"] == name), None)
+
+
+def help_text(manifests: dict, app: str | None = None) -> str:
+    apps = [manifests[app]] if app in manifests else list(manifests.values())
+    blocks = []
+    for m in apps:
+        lines = [f"{m['app']}: {m['summary']}"] + [f"  {c['usage']}  -  {c['summary']}" for c in m["commands"]]
+        blocks.append("\n".join(lines))
+    head = "" if app in manifests else ("Unknown app: " + app + "\n\n" if app else "")
+    return head + "\n\n".join(blocks)
+
+
+def list_text(manifests: dict) -> str:
+    return "\n".join(f"/{m['app']}  " + " · ".join(c["verb"] for c in m["commands"]) for m in manifests.values())
+
+
+def bot_commands(manifests: dict) -> list[dict]:
+    """Telegram's '/' menu (setMyCommands): help, list, then one entry per app."""
+    menu = [{"command": "help", "description": "every command, or /help <app>"},
+            {"command": "list", "description": "apps and their commands"}]
+    return menu + [{"command": m["app"], "description": m["summary"][:60]} for m in manifests.values() if m["app"] != "hub"]

telefi/compat.py

@@ -0,0 +1,35 @@
+"""A minimal direct-send API for simple scripts.
+
+`TelegramChannel(token, chat).send(title, body, level, reply_markup=...)` keeps working, but sends
+through TeleFi's one Bot API client (`adapters.telegram_call`). Prefer publishing envelopes
+(`telefi.envelope` + `telefi.publish`): they get routing, dedup, records and replies.
+"""
+from __future__ import annotations
+
+import html
+from typing import Callable
+
+from telefi.adapters import telegram_call
+
+TELEGRAM_MAX_BODY = 3800
+
+
+class TelegramChannel:
+    name = "telegram"
+    external = True
+
+    def __init__(self, bot_token: str | None, chat_id: str | None, *, opener: Callable | None = None) -> None:
+        self.bot_token, self.chat_id, self._opener = bot_token, chat_id, opener
+
+    def is_configured(self) -> bool:
+        return bool(self.bot_token and self.chat_id)
+
+    def send(self, title: str, body: str, level: str = "info", *, reply_markup: dict | None = None, **meta) -> bool:
+        """Same message shape as before: bold title, preformatted body, optional inline keyboard."""
+        if not self.is_configured():
+            return False
+        text = f"<b>{html.escape(title)}</b>\n\n<pre>{html.escape(body[:TELEGRAM_MAX_BODY])}</pre>"
+        payload = {"chat_id": self.chat_id, "text": text, "parse_mode": "HTML"}
+        if reply_markup is not None:
+            payload["reply_markup"] = reply_markup
+        return telegram_call(self.bot_token, "sendMessage", payload, opener=self._opener)["ok"]

telefi/core.py

@@ -0,0 +1,291 @@
+"""TeleFi core: config, publish, route, drain, the local record.
+
+    spool/out/<id>.json      published, not yet delivered
+    spool/done/<id>.json     delivered (or deduplicated / acknowledged); pruned after 7 days
+    spool/failed/<id>.json   rejected (schema) or undeliverable after retries, with <id>.error.txt
+    spool/in/<namespace>/    inbound events for a namespace's queue sink
+    spool/state/             acks.json, attempts.json, pending_prompts.json, telegram.json
+    outbox.jsonl             one line per envelope: the envelope + every channel's delivery result
+    inbox.jsonl              one line per inbound event and where it went
+
+Design: docs/DESIGN.md. Contracts: telefi/schemas/*.json. Format: render.py. Rotation: logs.py.
+"""
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from telefi import logs, schema
+from telefi.adapters import build_adapters
+
+# TELEFI_* is current; the legacy NOTIFLY_* names are still read for installs that predate the rename.
+HOME = Path(os.environ.get("TELEFI_HOME") or os.environ.get("NOTIFLY_HOME") or Path.home() / ".telefi")
+CONFIG_PATH = HOME / "hub.json"
+OUTBOX_SCAN_LINES = 5000
+DEFAULT_ACK_DAYS = 7
+DONE_RETENTION_DAYS = 7
+MAX_DELIVERY_ATTEMPTS = 10        # with backoff 30 s .. 1 h, about 6 hours of retrying
+RETRY_BASE_S = 30
+RETRY_MAX_S = 3600
+
+DEFAULT_CONFIG: dict = {
+    "schema": "telefi.hub_config.v1",
+    "mode": "live",
+    "dedup_window_min": 360,
+    "channels": {
+        "telegram": {"type": "telegram", "token_env": "TELEGRAM_BOT_TOKEN", "chat_env": "TELEGRAM_CHAT_ID"},
+        "file": {"type": "file", "path": "bell.jsonl"},
+    },
+    "routes": [
+        {"match": {"severity": ["error", "critical"]}, "channels": ["telegram", "file"]},
+        {"match": {"kind": ["blocker", "review", "result"]}, "channels": ["telegram", "file"]},
+        {"match": {}, "channels": ["file"]},
+    ],
+    "inbound": {"enabled": False, "channel": "telegram", "ack_days": DEFAULT_ACK_DAYS,
+                "commands": {},
+                "sinks": {"*": {"type": "queue"}}},
+}
+
+
+now_iso = logs.now_iso
+
+
+def load_config(path: Path = CONFIG_PATH) -> dict:
+    cfg = json.loads(path.read_text(encoding="utf-8")) if path.exists() else DEFAULT_CONFIG
+    bad = schema.validate(cfg, "hub_config.v1")
+    if bad:
+        raise ValueError(f"hub config {path}: " + "; ".join(bad))
+    logs.configure(cfg)
+    return cfg
+
+
+def resolve(raw: str) -> Path:
+    """A config path: `~` expands; a relative path is relative to TELEFI_HOME (so a config copied
+    into a throwaway home never writes to the real one)."""
+    p = Path(os.path.expanduser(raw))
+    return p if p.is_absolute() else HOME / p
+
+
+def spool_root(cfg: dict) -> Path:
+    env = os.environ.get("TELEFI_SPOOL") or os.environ.get("NOTIFLY_HUB_SPOOL")
+    return Path(os.path.expanduser(env)) if env else resolve(cfg.get("spool", "spool"))
+
+
+def append_jsonl(path: Path, rec: dict) -> None:
+    logs.append(path, rec)
+
+
+def read_state(root: Path, name: str) -> dict:
+    p = root / "state" / name
+    return json.loads(p.read_text(encoding="utf-8")) if p.exists() else {}
+
+
+def write_state(root: Path, name: str, data: dict) -> None:
+    p = root / "state" / name
+    p.parent.mkdir(parents=True, exist_ok=True)
+    tmp = p.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data), encoding="utf-8")
+    os.replace(tmp, p)
+
+
+# ---------------------------------------------------------------- publish (producer side)
+
+
+def envelope(*, source: str, kind: str, severity: str, title: str, insight: str = "", body: str = "",
+             evidence: dict | None = None, actions: list | None = None, dedup_key: str | None = None,
+             not_before: str | None = None, dedup_window_min: float | None = None) -> dict:
+    env = {"schema": "telefi.envelope.v1", "id": f"{source}-{uuid.uuid4().hex[:12]}", "source": source,
+           "kind": kind, "severity": severity, "title": title[:200], "body": body[:3500], "created_at": now_iso()}
+    if insight:
+        env["insight"] = insight[:300]
+    if evidence:
+        env["evidence"] = evidence
+    if actions:
+        env["actions"] = actions
+    if dedup_key:
+        env["dedup_key"] = dedup_key[:200]
+    if not_before:
+        env["not_before"] = not_before
+    if dedup_window_min is not None:
+        env["dedup_window_min"] = dedup_window_min
+    return env
+
+
+def publish(env: dict, *, spool: Path | None = None) -> Path:
+    """Validate, then write atomically into <spool>/out/. Raises ValueError on a schema violation."""
+    bad = schema.validate(env, "envelope.v1")
+    if bad:
+        raise ValueError("; ".join(bad))
+    out = (spool or spool_root(DEFAULT_CONFIG)) / "out"
+    out.mkdir(parents=True, exist_ok=True)
+    tmp = out / f".{env['id']}.tmp"
+    tmp.write_text(json.dumps(env, ensure_ascii=False), encoding="utf-8")
+    dest = out / f"{env['id']}.json"
+    os.replace(tmp, dest)
+    return dest
+
+
+# ---------------------------------------------------------------- route + drain
+
+
+def route(env: dict, cfg: dict) -> list[str]:
+    for r in cfg["routes"]:
+        if all(env.get(k) in v for k, v in r["match"].items()):
+            return r["channels"]
+    return []
+
+
+def outbox_path(root: Path) -> Path:
+    return root.parent / "outbox.jsonl"
+
+
+def outbox_records(root: Path) -> list[dict]:
+    return logs.read(outbox_path(root), last=OUTBOX_SCAN_LINES)
+
+
+def find_envelope(root: Path, envelope_id: str) -> dict | None:
+    for rec in reversed(outbox_records(root)):
+        if rec.get("envelope", {}).get("id") == envelope_id:
+            return rec["envelope"]
+    return None
+
+
+def sent_messages(root: Path) -> dict[str, str]:
+    """Telegram message id -> envelope id, for every hub message that reached Telegram."""
+    out = {}
+    for rec in outbox_records(root):
+        for d in rec.get("deliveries", []):
+            if d.get("channel") == "telegram" and d.get("message_id") is not None:
+                out[str(d["message_id"])] = rec["envelope"]["id"]
+    return out
+
+
+def conversation_path(root: Path) -> Path:
+    return root.parent / "conversation.jsonl"
+
+
+def ack(root: Path, dedup_key: str) -> None:
+    acks = read_state(root, "acks.json")
+    acks[dedup_key] = now_iso()
+    write_state(root, "acks.json", acks)
+
+
+def _acked(root: Path, days: float) -> set[str]:
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=days)).isoformat()
+    return {k for k, at in read_state(root, "acks.json").items() if at >= cutoff}
+
+
+def _last_delivered(root: Path) -> dict[str, str]:
+    """dedup_key -> when it was last delivered to at least one channel."""
+    last: dict[str, str] = {}
+    for r in outbox_records(root):
+        key = r.get("envelope", {}).get("dedup_key")
+        if key and any(d.get("ok") for d in r.get("deliveries", [])):
+            last[key] = max(last.get(key, ""), r.get("at", ""))
+    return last
+
+
+def _ago(minutes: float) -> str:
+    return (datetime.now(timezone.utc) - timedelta(minutes=minutes)).isoformat(timespec="seconds")
+
+
+def _when(raw: str) -> datetime | None:
+    """An ISO time in any offset -> aware UTC datetime (a naive one is read as UTC); None if invalid."""
+    try:
+        t = datetime.fromisoformat(raw)
+    except (TypeError, ValueError):
+        return None
+    return (t if t.tzinfo else t.replace(tzinfo=timezone.utc)).astimezone(timezone.utc)
+
+
+def _move(p: Path, folder: Path) -> None:
+    folder.mkdir(parents=True, exist_ok=True)
+    os.replace(p, folder / p.name)
+
+
+def _quarantine(p: Path, root: Path, reasons: list[str]) -> None:
+    _move(p, root / "failed")
+    (root / "failed" / f"{p.stem}.error.txt").write_text("\n".join(reasons), encoding="utf-8")
+
+
+def prune_done(root: Path, *, days: float = DONE_RETENTION_DAYS) -> int:
+    """Delete delivered envelopes older than `days` (their record stays in outbox.jsonl)."""
+    cutoff = datetime.now(timezone.utc).timestamp() - days * 86400
+    n = 0
+    for p in (root / "done").glob("*.json"):
+        if p.stat().st_mtime < cutoff:
+            p.unlink(missing_ok=True)
+            n += 1
+    return n
+
+
+def drain(cfg: dict, *, adapters: dict | None = None, spool: Path | None = None) -> list[dict]:
+    """Deliver every due envelope in <spool>/out. Returns the outbox records written.
+
+    A delivery that reaches no channel is retried with exponential backoff (state/attempts.json)
+    and quarantined in failed/ after MAX_DELIVERY_ATTEMPTS, so a Telegram outage never loses a
+    message. Every attempt is recorded in outbox.jsonl."""
+    root = spool or spool_root(cfg)
+    adapters = adapters if adapters is not None else build_adapters(cfg, resolve=resolve)
+    inbound = cfg.get("inbound", {})
+    buttons = bool(inbound.get("enabled"))
+    last = _last_delivered(root)
+    acked = _acked(root, inbound.get("ack_days", DEFAULT_ACK_DAYS))
+    attempts = read_state(root, "attempts.json")
+    now = datetime.now(timezone.utc)
+    records = []
+    for p in sorted((root / "out").glob("*.json")):
+        try:
+            env = json.loads(p.read_text(encoding="utf-8"))
+            bad = schema.validate(env, "envelope.v1")
+        except FileNotFoundError:                       # another drainer took it
+            continue
+        except ValueError as ex:
+            env, bad = {"id": p.stem}, [f"unreadable JSON: {ex}"]
+        if not bad and env.get("not_before") and _when(env["not_before"]) is None:
+            bad = [f"$.not_before: {env['not_before']!r} is not an ISO time"]
+        if not bad and env.get("not_before") and _when(env["not_before"]) > now:
+            continue                                    # held: a grace period is still running
+        retry = attempts.get(p.stem)
+        if retry and (_when(retry["next"]) or now) > now:
+            continue                                    # backing off after a failed delivery
+        key = env.get("dedup_key")
+        window = env.get("dedup_window_min", cfg.get("dedup_window_min", 360))
+        if bad:
+            _quarantine(p, root, bad)
+            rec = {"at": now_iso(), "envelope": env, "rejected": bad, "deliveries": []}
+        elif key in acked:
+            _move(p, root / "done")
+            rec = {"at": now_iso(), "envelope": env, "acknowledged": True, "deliveries": []}
+        elif key and last.get(key, "") >= _ago(window):
+            _move(p, root / "done")
+            rec = {"at": now_iso(), "envelope": env, "deduplicated": True, "deliveries": []}
+        else:
+            deliveries = []
+            for name in route(env, cfg):
+                a = adapters.get(name)
+                res = a.send(env, buttons=buttons) if a else {"ok": False, "error": f"no channel named {name}"}
+                deliveries.append({"channel": name, **res})
+            rec = {"at": now_iso(), "envelope": env, "deliveries": deliveries}
+            if not deliveries or any(d["ok"] for d in deliveries):
+                _move(p, root / "done")
+                attempts.pop(p.stem, None)
+                if key and deliveries:
+                    last[key] = rec["at"]
+            else:
+                n = (retry or {}).get("n", 0) + 1
+                if n >= MAX_DELIVERY_ATTEMPTS:
+                    _quarantine(p, root, [f"{n} delivery attempts failed: {d['channel']}: {d['error']}" for d in deliveries])
+                    attempts.pop(p.stem, None)
+                    rec["gave_up"] = n
+                else:
+                    wait = min(RETRY_BASE_S * 2 ** (n - 1), RETRY_MAX_S)
+                    attempts[p.stem] = {"n": n, "next": (now + timedelta(seconds=wait)).isoformat(timespec="seconds")}
+                    rec["retry_in_s"] = wait
+        append_jsonl(outbox_path(root), rec)
+        records.append(rec)
+    write_state(root, "attempts.json", attempts)
+    return records