synckey 0.1.0__py3-none-any.whl

synckey/config.py

@@ -0,0 +1,150 @@
+"""Configuration and paths.
+
+State lives under $SYNCKEY_HOME (default ~/.synckey):
+    secret.key   Fernet key for sealing provider credentials (0600)
+    synckey.db   SQLite: keys, usage, events, key state, metadata
+    config.toml  user settings and custom providers
+
+The unified gateway key is generated once at init time; only its SHA-256 hash
+is persisted, so the plaintext is shown exactly once.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+UNIFIED_KEY_PREFIX = "sk-synckey-"
+
+
+def home() -> Path:
+    return Path(os.environ.get("SYNCKEY_HOME", Path.home() / ".synckey"))
+
+
+def secret_key_path() -> Path:
+    return home() / "secret.key"
+
+
+def db_path() -> Path:
+    return Path(os.environ.get("SYNCKEY_DB", home() / "synckey.db"))
+
+
+def config_path() -> Path:
+    return home() / "config.toml"
+
+
+@dataclass
+class Settings:
+    host: str = "127.0.0.1"
+    port: int = 8787
+    request_timeout: float = 120.0
+    max_connections: int = 600
+    max_keepalive: int = 300
+    # Fallback: ordered preference when several providers serve the same model.
+    provider_priority: list[str] = field(default_factory=list)
+    cross_provider_fallback: bool = True
+    # Per-request attempt budget across the key pool.
+    max_retries: int = 6
+    default_cooldown: float = 20.0
+    # Tier fallback: allow cross-tier fallback to same-tier alternatives.
+    tier_fallback_enabled: bool = True
+    # Seconds of cooldown remaining before we skip to tier alternatives entirely.
+    deep_cooling_threshold: float = 60.0
+    # User-defined model -> tier overrides, e.g. {"my-model": "frontier"}.
+    tier_overrides: dict[str, str] = field(default_factory=dict)
+    # User-defined model pricing overrides, e.g. {"my-model": [1.0, 3.0]}.
+    price_overrides: dict[str, list] = field(default_factory=dict)
+    custom_providers: list[dict] = field(default_factory=list)
+    # Deferred queue: when all keys are cooling, accept the request, return a
+    # request id, run it when capacity frees, and serve the result on a later GET.
+    deferred_enabled: bool = True
+    deferred_ttl: float = 3600.0          # keep a finished response this long, then purge
+    deferred_poll: float = 5.0            # worker scan interval (seconds)
+    deferred_max_queue: int = 1000        # reject new deferrals beyond this many queued
+    deferred_max_queue_age: float = 86400.0  # drop a job that never ran within this window
+
+    @classmethod
+    def load(cls) -> "Settings":
+        path = config_path()
+        if not path.exists():
+            return cls()
+        data = tomllib.loads(path.read_text())
+        gw = data.get("gateway", {})
+        routing = data.get("routing", {})
+        tiers = data.get("tiers", {})
+        deferred = data.get("deferred", {})
+        return cls(
+            host=gw.get("host", cls.host),
+            port=gw.get("port", cls.port),
+            request_timeout=gw.get("request_timeout", cls.request_timeout),
+            max_connections=gw.get("max_connections", cls.max_connections),
+            max_keepalive=gw.get("max_keepalive", cls.max_keepalive),
+            provider_priority=routing.get("priority", []),
+            cross_provider_fallback=routing.get("cross_provider_fallback", True),
+            max_retries=routing.get("max_retries", cls.max_retries),
+            default_cooldown=routing.get("default_cooldown", cls.default_cooldown),
+            tier_fallback_enabled=routing.get("tier_fallback", True),
+            deep_cooling_threshold=routing.get("deep_cooling_threshold", cls.deep_cooling_threshold),
+            tier_overrides=tiers.get("overrides", {}),
+            price_overrides=tiers.get("prices", {}),
+            custom_providers=data.get("providers", []),
+            deferred_enabled=deferred.get("enabled", True),
+            deferred_ttl=deferred.get("ttl", cls.deferred_ttl),
+            deferred_poll=deferred.get("poll", cls.deferred_poll),
+              deferred_max_queue=deferred.get("max_queue", cls.deferred_max_queue),
+              deferred_max_queue_age=deferred.get("max_queue_age", cls.deferred_max_queue_age),
+          )
+
+    def save(self) -> None:
+        """Write current settings back to config.toml."""
+        import tomllib
+
+        path = config_path()
+        data = {}
+        if path.exists():
+            try:
+                data = tomllib.loads(path.read_text())
+            except Exception:
+                pass
+        data.setdefault("gateway", {})["host"] = self.host
+        data.setdefault("gateway", {})["port"] = self.port
+        data.setdefault("gateway", {})["request_timeout"] = self.request_timeout
+        data.setdefault("gateway", {})["max_connections"] = self.max_connections
+        data.setdefault("gateway", {})["max_keepalive"] = self.max_keepalive
+        data.setdefault("routing", {})["priority"] = self.provider_priority
+        data.setdefault("routing", {})["cross_provider_fallback"] = self.cross_provider_fallback
+        data.setdefault("routing", {})["max_retries"] = self.max_retries
+        data.setdefault("routing", {})["default_cooldown"] = self.default_cooldown
+        data.setdefault("routing", {})["tier_fallback"] = self.tier_fallback_enabled
+        data.setdefault("routing", {})["deep_cooling_threshold"] = self.deep_cooling_threshold
+        data.setdefault("tiers", {})["overrides"] = self.tier_overrides
+        data.setdefault("tiers", {})["prices"] = self.price_overrides
+        data["providers"] = self.custom_providers
+        data.setdefault("deferred", {})["enabled"] = self.deferred_enabled
+        data.setdefault("deferred", {})["ttl"] = self.deferred_ttl
+        data.setdefault("deferred", {})["poll"] = self.deferred_poll
+        data.setdefault("deferred", {})["max_queue"] = self.deferred_max_queue
+        data.setdefault("deferred", {})["max_queue_age"] = self.deferred_max_queue_age
+
+        try:
+            import tomli
+        except ImportError:
+            import toml as tomli
+        path.write_text(tomli.dumps(data))
+
+
+def ensure_home() -> Path:
+    h = home()
+    h.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(h, 0o700)
+    except OSError:
+        pass
+    return h
+
+
+def generate_unified_key() -> str:
+    return UNIFIED_KEY_PREFIX + secrets.token_urlsafe(32)

synckey/context.py

@@ -0,0 +1,75 @@
+"""Shared runtime wiring."""
+
+from __future__ import annotations
+
+import os
+
+from .config import Settings, db_path, secret_key_path
+from .crypto import SecretBox
+from .db import Database
+from .keypool import KeyPool
+from .prefs import Prefs
+from .providers import BUILTIN, Provider
+from .router import Router
+from .state import StateStore
+from .tiers import load_overrides
+
+
+def merged_providers(settings: Settings) -> dict[str, Provider]:
+    providers = dict(BUILTIN)
+    for spec in settings.custom_providers:
+        try:
+            prov = Provider(
+                id=spec["id"],
+                name=spec.get("name", spec["id"]),
+                base_url=spec["base_url"],
+                models_path=spec.get("models_path", "/models"),
+                env=tuple(spec.get("env", ())),
+                patterns=tuple(spec.get("patterns", ())),
+                auth=spec.get("auth", "bearer"),
+                signup=spec.get("signup", ""),
+                notes=spec.get("notes", ""),
+            )
+            providers[prov.id] = prov
+        except KeyError:
+            continue
+    return providers
+
+
+class Context:
+    def __init__(self) -> None:
+        self.settings = Settings.load()
+        self.providers = merged_providers(self.settings)
+        self.box = SecretBox(secret_key_path())
+        self.db = Database(db_path())
+        self.prefs = Prefs(self.db)
+        # Tier overrides come from two places: config.toml (static, versioned) and
+        # the DB (set via `synckey tier set`). DB wins on conflict.
+        merged_tiers = {**self.settings.tier_overrides, **self.prefs.tier_overrides()}
+        load_overrides(merged_tiers, self.settings.price_overrides)
+        self.states = StateStore(self.db.path)
+        self.pool = KeyPool(
+            self.db,
+            self.box,
+            self.states,
+            default_cooldown=self.settings.default_cooldown,
+        )
+        self.router = Router(self.db, self.providers, self.settings, self.prefs)
+
+    def first_secret(self, provider_id: str) -> str | None:
+        keys = self.db.list_keys(provider=provider_id, enabled_only=True)
+        if keys:
+            return self.box.open(keys[0].secret)
+        prov = self.providers.get(provider_id)
+        if prov:
+            for env in prov.env:
+                if os.environ.get(env):
+                    return os.environ[env]
+        return None
+
+    def unified_key_hash(self) -> str | None:
+        return self.db.get_meta("unified_key_hash")
+
+    def close(self) -> None:
+        self.states.close()
+        self.db.close()

synckey/crypto.py

@@ -0,0 +1,41 @@
+"""At-rest encryption for stored provider secrets.
+
+One symmetric key lives in ~/.synckey/secret.key with 0600 perms. Provider
+credentials are sealed with Fernet so the database never holds plaintext. Lose
+the secret file and the stored credentials are unrecoverable by design.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from cryptography.fernet import Fernet, InvalidToken
+
+
+class SecretBox:
+    def __init__(self, key_path: Path):
+        self.key_path = key_path
+        self._fernet = Fernet(self._load_or_create())
+
+    def _load_or_create(self) -> bytes:
+        if self.key_path.exists():
+            return self.key_path.read_bytes()
+        self.key_path.parent.mkdir(parents=True, exist_ok=True)
+        key = Fernet.generate_key()
+        fd = os.open(self.key_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(key)
+        return key
+
+    def seal(self, plaintext: str) -> bytes:
+        return self._fernet.encrypt(plaintext.encode("utf-8"))
+
+    def open(self, token: bytes) -> str:
+        try:
+            return self._fernet.decrypt(token).decode("utf-8")
+        except InvalidToken as exc:
+            raise RuntimeError(
+                "Could not decrypt a stored secret. The secret.key file may have "
+                "changed. Re-add affected keys with `synckey setup`."
+            ) from exc

synckey/db.py

@@ -0,0 +1,426 @@
+"""SQLite persistence: credentials, usage records, events, metadata."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS meta (
+    name  TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS keys (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    provider   TEXT    NOT NULL,
+    label      TEXT    NOT NULL,
+    secret     BLOB    NOT NULL,
+    enabled    INTEGER NOT NULL DEFAULT 1,
+    weight     INTEGER NOT NULL DEFAULT 1,
+    rpm_limit  REAL,
+    tpm_limit  REAL,
+    created_at REAL    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS usage (
+    id                INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts                REAL    NOT NULL,
+    provider          TEXT    NOT NULL,
+    model             TEXT    NOT NULL,
+    key_id            INTEGER,
+    prompt_tokens     INTEGER NOT NULL DEFAULT 0,
+    completion_tokens INTEGER NOT NULL DEFAULT 0,
+    total_tokens      INTEGER NOT NULL DEFAULT 0,
+    cost_usd          REAL,
+    status_code       INTEGER NOT NULL DEFAULT 0,
+    latency_ms        INTEGER NOT NULL DEFAULT 0,
+    stream            INTEGER NOT NULL DEFAULT 0,
+    tier              INTEGER,
+    error             TEXT
+);
+
+CREATE TABLE IF NOT EXISTS events (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts          REAL    NOT NULL,
+    type        TEXT    NOT NULL,
+    key_id      INTEGER,
+    provider    TEXT,
+    model       TEXT,
+    fallback_to TEXT,
+    tier_from   INTEGER,
+    tier_to     INTEGER,
+    chain       TEXT,
+    message     TEXT
+);
+
+CREATE TABLE IF NOT EXISTS deferred (
+    id            TEXT    PRIMARY KEY,
+    created_at    REAL    NOT NULL,
+    status        TEXT    NOT NULL,        -- queued | running | done | error
+    path          TEXT    NOT NULL,        -- e.g. /chat/completions
+    body          TEXT    NOT NULL,        -- JSON request body (non-stream)
+    model         TEXT,                    -- original model string (may be null)
+    provider_hint TEXT,
+    floor         INTEGER,
+    eta           REAL,                    -- approx unix time the call can run
+    response      BLOB,                    -- stored upstream bytes when done
+    status_code   INTEGER,
+    error         TEXT,
+    completed_at  REAL,
+    attempts      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage(ts);
+CREATE INDEX IF NOT EXISTS idx_usage_provider ON usage(provider);
+CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
+CREATE INDEX IF NOT EXISTS idx_keys_provider ON keys(provider);
+CREATE INDEX IF NOT EXISTS idx_deferred_status ON deferred(status);
+
+CREATE TABLE IF NOT EXISTS routing_chains (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts         REAL    NOT NULL,
+    model      TEXT    NOT NULL,
+    provider   TEXT    NOT NULL,
+    key_id     INTEGER,
+    chain      TEXT    NOT NULL
+);
+"""
+
+USAGE_COLS = (
+    "ts, provider, model, key_id, prompt_tokens, completion_tokens, "
+    "total_tokens, cost_usd, status_code, latency_ms, stream, tier, error"
+)
+USAGE_INSERT = f"INSERT INTO usage({USAGE_COLS}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)"
+
+
+def tune(conn: sqlite3.Connection) -> None:
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA busy_timeout=5000")
+    conn.execute("PRAGMA temp_store=MEMORY")
+    conn.execute("PRAGMA cache_size=-8000")
+
+
+@dataclass
+class KeyRecord:
+    id: int
+    provider: str
+    label: str
+    secret: bytes
+    enabled: bool
+    weight: int
+    rpm_limit: float | None
+    tpm_limit: float | None
+    created_at: float
+
+
+def sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+class Database:
+    def __init__(self, path: Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(self.path, check_same_thread=False)
+        self.conn.row_factory = sqlite3.Row
+        tune(self.conn)
+        self.conn.executescript(SCHEMA)
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    # meta
+    def set_meta(self, name: str, value: str) -> None:
+        self.conn.execute(
+            "INSERT INTO meta(name, value) VALUES(?,?) "
+            "ON CONFLICT(name) DO UPDATE SET value=excluded.value",
+            (name, value),
+        )
+        self.conn.commit()
+
+    def get_meta(self, name: str) -> str | None:
+        row = self.conn.execute("SELECT value FROM meta WHERE name=?", (name,)).fetchone()
+        return row["value"] if row else None
+
+    def get_json(self, name: str, default=None):
+        raw = self.get_meta(name)
+        if not raw:
+            return default
+        try:
+            return json.loads(raw)
+        except ValueError:
+            return default
+
+    def set_json(self, name: str, obj) -> None:
+        self.set_meta(name, json.dumps(obj))
+
+    # keys
+    def add_key(
+        self,
+        provider: str,
+        label: str,
+        secret: bytes,
+        weight: int = 1,
+        rpm_limit: float | None = None,
+        tpm_limit: float | None = None,
+    ) -> int:
+        cur = self.conn.execute(
+            "INSERT INTO keys(provider, label, secret, weight, rpm_limit, tpm_limit, created_at) "
+            "VALUES(?,?,?,?,?,?,?)",
+            (provider, label, secret, weight, rpm_limit, tpm_limit, time.time()),
+        )
+        self.conn.commit()
+        return int(cur.lastrowid)
+
+    def remove_key(self, key_id: int) -> bool:
+        cur = self.conn.execute("DELETE FROM keys WHERE id=?", (key_id,))
+        self.conn.commit()
+        return cur.rowcount > 0
+
+    def set_key_enabled(self, key_id: int, enabled: bool) -> None:
+        self.conn.execute("UPDATE keys SET enabled=? WHERE id=?", (1 if enabled else 0, key_id))
+        self.conn.commit()
+
+    def set_key_limits(self, key_id: int, rpm: float | None, tpm: float | None) -> None:
+        self.conn.execute(
+            "UPDATE keys SET rpm_limit=?, tpm_limit=? WHERE id=?", (rpm, tpm, key_id)
+        )
+        self.conn.commit()
+
+    def list_keys(self, provider: str | None = None, enabled_only: bool = False) -> list[KeyRecord]:
+        sql = "SELECT * FROM keys"
+        clauses, params = [], []
+        if provider:
+            clauses.append("provider=?")
+            params.append(provider)
+        if enabled_only:
+            clauses.append("enabled=1")
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        sql += " ORDER BY provider, id"
+        return [
+            KeyRecord(
+                id=r["id"],
+                provider=r["provider"],
+                label=r["label"],
+                secret=r["secret"],
+                enabled=bool(r["enabled"]),
+                weight=r["weight"],
+                rpm_limit=r["rpm_limit"],
+                tpm_limit=r["tpm_limit"],
+                created_at=r["created_at"],
+            )
+            for r in self.conn.execute(sql, params).fetchall()
+        ]
+
+    def providers_with_keys(self) -> list[str]:
+        rows = self.conn.execute(
+            "SELECT DISTINCT provider FROM keys WHERE enabled=1 ORDER BY provider"
+        ).fetchall()
+        return [r["provider"] for r in rows]
+
+    def key_stats(self) -> dict[int, dict]:
+        """Per-key request/error/token/cost totals from usage log."""
+        rows = self.conn.execute(
+            "SELECT key_id, COUNT(*) reqs, "
+            "SUM(CASE WHEN status_code>=400 OR error IS NOT NULL THEN 1 ELSE 0 END) errs, "
+            "SUM(total_tokens) tokens, SUM(cost_usd) cost "
+            "FROM usage WHERE key_id IS NOT NULL GROUP BY key_id"
+        ).fetchall()
+        return {
+            r["key_id"]: {
+                "requests": r["reqs"],
+                "errors": r["errs"] or 0,
+                "tokens": r["tokens"] or 0,
+                "cost": r["cost"] or 0.0,
+            }
+            for r in rows
+        }
+
+    # events
+    def record_event(
+        self,
+        *,
+        type: str,
+        key_id: int | None = None,
+        provider: str | None = None,
+        model: str | None = None,
+        fallback_to: str | None = None,
+        tier_from: int | None = None,
+        tier_to: int | None = None,
+        chain: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.conn.execute(
+            "INSERT INTO events(ts,type,key_id,provider,model,fallback_to,tier_from,tier_to,chain,message) "
+            "VALUES(?,?,?,?,?,?,?,?,?,?)",
+            (time.time(), type, key_id, provider, model, fallback_to, tier_from, tier_to, chain, message),
+        )
+        self.conn.commit()
+
+    def record_routing_chain(
+        self,
+        *,
+        model: str,
+        provider: str,
+        key_id: int,
+        chain: str,
+    ) -> None:
+        """Record the full routing chain for a request for TUI view 4."""
+        self.conn.execute(
+            "INSERT INTO routing_chains(ts, model, provider, key_id, chain) VALUES(?,?,?,?,?)",
+            (time.time(), model, provider, key_id, chain),
+        )
+        self.conn.commit()
+
+    def recent_events(self, limit: int = 50, event_type: str | None = None) -> list[sqlite3.Row]:
+        if event_type:
+            return self.conn.execute(
+                "SELECT * FROM events WHERE type=? ORDER BY ts DESC LIMIT ?", (event_type, limit)
+            ).fetchall()
+        return self.conn.execute(
+            "SELECT * FROM events ORDER BY ts DESC LIMIT ?", (limit,)
+        ).fetchall()
+
+    def recent_routing_chains(self, limit: int = 20) -> list[sqlite3.Row]:
+        """Return the most recent routing chains for TUI view 4."""
+        return self.conn.execute(
+            "SELECT * FROM routing_chains ORDER BY ts DESC LIMIT ?", (limit,)
+        ).fetchall()
+
+    def routing_chain_by_id(self, chain_id: int) -> sqlite3.Row | None:
+        return self.conn.execute(
+            "SELECT * FROM routing_chains WHERE id=?", (chain_id,)
+        ).fetchone()
+
+    # usage reads
+    def usage_summary(self, since: float | None = None) -> list[sqlite3.Row]:
+        sql = (
+            "SELECT provider, model, tier, COUNT(*) requests, "
+            "SUM(prompt_tokens) prompt_tokens, SUM(completion_tokens) completion_tokens, "
+            "SUM(total_tokens) total_tokens, SUM(cost_usd) cost_usd, "
+            "SUM(CASE WHEN status_code>=400 OR error IS NOT NULL THEN 1 ELSE 0 END) errors, "
+            "AVG(latency_ms) avg_latency FROM usage"
+        )
+        params: list = []
+        if since is not None:
+            sql += " WHERE ts>=?"
+            params.append(since)
+        sql += " GROUP BY provider, model ORDER BY total_tokens DESC"
+        return self.conn.execute(sql, params).fetchall()
+
+    def usage_totals(self, since: float | None = None) -> sqlite3.Row:
+        sql = (
+            "SELECT COUNT(*) requests, SUM(total_tokens) total_tokens, "
+            "SUM(prompt_tokens) prompt_tokens, SUM(completion_tokens) completion_tokens, "
+            "SUM(cost_usd) cost_usd, "
+            "SUM(CASE WHEN status_code>=400 OR error IS NOT NULL THEN 1 ELSE 0 END) errors "
+            "FROM usage"
+        )
+        params: list = []
+        if since is not None:
+            sql += " WHERE ts>=?"
+            params.append(since)
+        return self.conn.execute(sql, params).fetchone()
+
+    def recent_usage(self, limit: int = 25) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM usage ORDER BY ts DESC LIMIT ?", (limit,)
+        ).fetchall()
+
+    # deferred queue
+    def create_deferred(
+        self,
+        *,
+        id: str,
+        path: str,
+        body: str,
+        model: str | None,
+        provider_hint: str | None,
+        floor: int | None,
+        eta: float | None,
+    ) -> None:
+        self.conn.execute(
+            "INSERT INTO deferred(id, created_at, status, path, body, model, "
+            "provider_hint, floor, eta) VALUES(?,?,?,?,?,?,?,?,?)",
+            (id, time.time(), "queued", path, body, model, provider_hint, floor, eta),
+        )
+        self.conn.commit()
+
+    def get_deferred(self, id: str) -> sqlite3.Row | None:
+        return self.conn.execute("SELECT * FROM deferred WHERE id=?", (id,)).fetchone()
+
+    def queued_deferred(self, limit: int = 50) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM deferred WHERE status='queued' ORDER BY created_at LIMIT ?",
+            (limit,),
+        ).fetchall()
+
+    def count_deferred(self, status: str | None = None) -> int:
+        if status:
+            row = self.conn.execute(
+                "SELECT COUNT(*) c FROM deferred WHERE status=?", (status,)
+            ).fetchone()
+        else:
+            row = self.conn.execute("SELECT COUNT(*) c FROM deferred").fetchone()
+        return row["c"]
+
+    def recent_deferred(self, limit: int = 50) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM deferred ORDER BY created_at DESC LIMIT ?", (limit,)
+        ).fetchall()
+
+    def set_deferred_running(self, id: str) -> None:
+        self.conn.execute(
+            "UPDATE deferred SET status='running', attempts=attempts+1 WHERE id=?", (id,)
+        )
+        self.conn.commit()
+
+    def requeue_deferred(self, id: str, eta: float | None) -> None:
+        self.conn.execute(
+            "UPDATE deferred SET status='queued', eta=? WHERE id=?", (eta, id)
+        )
+        self.conn.commit()
+
+    def complete_deferred(self, id: str, status_code: int, response: bytes) -> None:
+        self.conn.execute(
+            "UPDATE deferred SET status='done', status_code=?, response=?, completed_at=? "
+            "WHERE id=?",
+            (status_code, response, time.time(), id),
+        )
+        self.conn.commit()
+
+    def fail_deferred(self, id: str, status_code: int, error: str) -> None:
+        self.conn.execute(
+            "UPDATE deferred SET status='error', status_code=?, error=?, completed_at=? "
+            "WHERE id=?",
+            (status_code, error[:500], time.time(), id),
+        )
+        self.conn.commit()
+
+    def reset_running_deferred(self) -> int:
+        """On startup, return any 'running' jobs (from a crash) to the queue."""
+        cur = self.conn.execute(
+            "UPDATE deferred SET status='queued' WHERE status='running'"
+        )
+        self.conn.commit()
+        return cur.rowcount
+
+    def purge_deferred(self, ttl: float, max_queue_age: float) -> int:
+        """Delete finished jobs older than `ttl` and queued jobs stuck past `max_queue_age`."""
+        now = time.time()
+        cur = self.conn.execute(
+            "DELETE FROM deferred WHERE "
+            "(status IN ('done','error') AND completed_at IS NOT NULL AND completed_at < ?) "
+            "OR (status='queued' AND created_at < ?)",
+            (now - ttl, now - max_queue_age),
+        )
+        self.conn.commit()
+        return cur.rowcount