keywright-server 0.0.1__py3-none-any.whl

keywright_server/notify/base.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from .. import semantic
+from ..audit import _scrub
+from ..models import AccessRequest, Agent, Nudge
+
+
+@dataclass
+class Field:
+    """One input on the driver's settings form. Rendered generically by the admin UI."""
+
+    name: str
+    label: str
+    type: str = "text"  # text | password | url | textarea | select | multiselect | checkbox
+    help: str = ""
+    required: bool = False
+    options: list[tuple[str, str]] = field(default_factory=list)  # (value, label) for selects
+    options_from_probe: str = ""  # key in ProbeResult.choices to populate options dynamically
+
+
+@dataclass
+class ProbeResult:
+    ok: bool
+    message: str = ""
+    info: dict[str, Any] = field(default_factory=dict)
+    choices: dict[str, list[tuple[str, str]]] = field(default_factory=dict)  # field name -> options
+
+
+DecisionCallback = Callable[[str], Awaitable[None]]  # receives a signed decision token
+
+
+class Notifier(ABC):
+    id: str = ""
+    label: str = ""
+    description: str = ""
+    fields: ClassVar[list[Field]] = []
+    supports_actions: bool = False  # can render decision buttons (vs. links only)
+    max_actions: int = 3
+
+    def __init__(self, config: dict[str, Any]):
+        self.config = config
+
+    @abstractmethod
+    async def probe(self) -> ProbeResult:
+        """Validate the config and discover selectable targets. Never raises."""
+
+    @abstractmethod
+    async def send(self, req: AccessRequest, agent: Agent, links: dict[str, str], buttons: list[str]) -> None:
+        """Deliver the request. `links` maps scope -> signed decision URL (temporary approval scopes and deny).
+        `buttons` is the ordered subset of scopes to render as actions when supported."""
+
+    def capped(self, buttons: list[str]) -> list[str]:
+        """At most `max_actions` buttons, deny last and never the one that is dropped."""
+        allow = [b for b in buttons if b != "deny"]
+        if "deny" in buttons:
+            return [*allow[:self.max_actions - 1], "deny"]
+        return allow[:self.max_actions]
+
+    async def clear(self, req: AccessRequest) -> None:
+        """Called after a decision; drivers may retract the notification."""
+
+    async def send_nudge(self, nudge: Nudge, agent: Agent, url: str) -> None:
+        """Deliver "the agent needs you in the conversation". No decision comes back: the human
+        goes to the conversation. `url` opens the dashboard, where the nudge can also be cleared."""
+        raise NotImplementedError
+
+    async def clear_nudge(self, nudge: Nudge) -> None:
+        """Called once the human has cleared it; drivers may retract the notification."""
+
+    async def start(self, on_decision: DecisionCallback) -> None:
+        """Optional: start a background listener that feeds decisions back."""
+
+    async def stop(self) -> None:
+        """Optional: stop the background listener."""
+
+
+registry: dict[str, type[Notifier]] = {}
+
+
+def register(cls: type[Notifier]) -> type[Notifier]:
+    registry[cls.id] = cls
+    return cls
+
+
+def request_summary(req: AccessRequest, agent: Agent) -> tuple[str, str]:
+    from keywright.hazards import blocks, describe
+
+    from ..access import binds_exactly, hazard_level, hazards_of, operations, path_scoped
+
+    level = hazard_level(req.detail)
+    title = f"Keywright DESTRUCTIVE ({level}): {agent.name}" if blocks(level) else f"Keywright: {agent.name}"
+    groups = (req.detail or {}).get("bundles") or {}
+    grouped = {p for ps in groups.values() for p in ps}
+    lines = [f"bundle {name} ({len(ps)} patterns)" for name, ps in groups.items()]
+    lines += [p for p in req.patterns if p not in grouped]
+    pats = "\n".join(lines)
+    body = f"{pats}\n{req.reason}".strip()
+    if level:
+        body = f"FLAGGED {level}: {describe(hazards_of(req.detail))}\n" + body
+    jev = semantic.describe(getattr(req, "semantic", None))
+    if jev:
+        body += "\n" + jev
+    ops = [op for _, op in operations(req.detail)]
+    operation = "\n".join(operation_line(op) for op in ops)
+    if operation:
+        body += "\n" + operation[:300]
+        if len(operation) > 300:
+            body += "\n[Preview shortened. Open the request to review full details.]"
+    users = {op.get("user") for op in ops if op.get("user")}
+    if users:
+        body += f"\nRemote user: {', '.join(sorted(users))}"
+    if blocks(level):
+        body += "\nScope: this exact operation, once. Timed and standing access are not offered."
+    elif len(ops) > 1:
+        body += f"\nScope: these {len(ops)} operations exactly, each for every duration."
+    elif path_scoped(req.detail):
+        body += ("\nScope: these exact contents for every duration; 'This path, 15 min' allows any contents at "
+                 "this path for 15 minutes.")
+    elif binds_exactly(req.detail):
+        body += "\nScope: exact operation for every duration. Open the request to approve broader patterns."
+    else:
+        body += "\nScope: the listed permission patterns."
+    return title, body
+
+
+def nudge_summary(nudge: Nudge, agent: Agent) -> tuple[str, str]:
+    """Title and body for a nudge, in the shape the phone shows it."""
+    title = f"Keywright: {agent.name} needs you"
+    lines = [nudge.message]
+    where = " \u00b7 ".join(x for x in (nudge.context, nudge.session_id) if x)
+    if where:
+        lines.append(where)
+    return title, "\n".join(lines)
+
+
+def operation_line(op: dict) -> str:
+    """One line per operation, as the phone shows it: a command line, a file write as path, size and
+    digest (never the contents), a file read as its path, or a tool call's arguments."""
+    if op.get("command"):
+        if op.get("to_path"):
+            how = "append to" if op.get("append") else "write"
+            return f"$ {op['command']}\n  output -> {how} {op.get('to_host')}:{op['to_path']} (not returned to the agent)"
+        return f"$ {op['command']}"
+    if "sha256" in op:
+        return f"put {op.get('path')} ({op.get('bytes', '?')} bytes, sha256 {str(op['sha256'])[:12]})"
+    if "path" in op:
+        return f"get {op['path']}"
+    if "arguments" in op:
+        return json.dumps(_scrub(op["arguments"]), ensure_ascii=False)
+    return ""

keywright_server/notify/homeassistant.py

@@ -0,0 +1,221 @@
+"""Home Assistant driver.
+
+Sends actionable notifications through any `notify.*` service HA exposes (the companion app's
+`notify.mobile_app_*` services are the useful ones) and listens on HA's websocket for
+`mobile_app_notification_action` events so a tap on the phone becomes a decision without any
+HA automation. Everything is discovered from the HA instance with a long-lived access token.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Any, ClassVar
+
+import httpx
+import websockets
+
+from ..models import AccessRequest, Agent, Nudge
+from .base import (
+    DecisionCallback,
+    Field,
+    Notifier,
+    ProbeResult,
+    nudge_summary,
+    register,
+    request_summary,
+)
+
+log = logging.getLogger("keywright.notify.ha")
+ACTION_PREFIX = "GK:"
+
+
+@register
+class HomeAssistantNotifier(Notifier):
+    id = "homeassistant"
+    label = "Home Assistant (companion app)"
+    description = "Actionable push via notify.mobile_app_* services; taps come back over the HA websocket."
+    supports_actions = True
+    max_actions = 3  # Android caps at 3 buttons; iOS allows more but 3 keeps both consistent
+    fields: ClassVar[list[Field]] = [
+        Field("base_url", "Home Assistant URL", "url", required=True,
+              help="e.g. http://homeassistant.local:8123 or your Nabu Casa URL"),
+        Field("token", "Long-lived access token", "password", required=True,
+              help="Profile -> Security -> Long-lived access tokens. Stored in the Keywright database."),
+        Field("targets", "Notify services", "multiselect", options_from_probe="targets",
+              help="Probe first, then pick the phones to notify."),
+        Field("critical", "Mark as time-sensitive / high priority", "checkbox"),
+    ]
+
+    def __init__(self, config: dict[str, Any]):
+        super().__init__(config)
+        self._task: asyncio.Task | None = None
+        self._stop = asyncio.Event()
+
+    # ---- helpers ----------------------------------------------------------------------------
+    def _base(self) -> str:
+        return self.config.get("base_url", "").rstrip("/")
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.config.get('token', '')}", "Content-Type": "application/json"}
+
+    def _ws_url(self) -> str:
+        b = self._base()
+        return b.replace("https://", "wss://", 1).replace("http://", "ws://", 1) + "/api/websocket"
+
+    # ---- Notifier API -----------------------------------------------------------------------
+    async def probe(self) -> ProbeResult:
+        if not self._base() or not self.config.get("token"):
+            return ProbeResult(ok=False, message="URL and token are required.")
+        try:
+            async with httpx.AsyncClient(timeout=10, headers=self._headers()) as c:
+                cfg = await c.get(self._base() + "/api/config")
+                if cfg.status_code == 401:
+                    return ProbeResult(ok=False, message="HA rejected the token (401).")
+                cfg.raise_for_status()
+                svc = await c.get(self._base() + "/api/services")
+                svc.raise_for_status()
+        except httpx.HTTPError as e:
+            return ProbeResult(ok=False, message=f"Could not reach Home Assistant: {e}")
+        info = cfg.json()
+        notify = next((d for d in svc.json() if d.get("domain") == "notify"), {})
+        services = notify.get("services", {}) or {}
+        targets: list[tuple[str, str]] = []
+        for name, meta in sorted(services.items()):
+            if name in ("send_message", "persistent_notification"):
+                continue
+            label = (meta or {}).get("name") or name
+            if name.startswith("mobile_app_"):
+                label = f"{label} (companion app)"
+            targets.append((name, label))
+        msg = f"Connected to {info.get('location_name', 'Home Assistant')} {info.get('version', '')}: " \
+              f"{len(targets)} notify services."
+        return ProbeResult(ok=True, message=msg, info={"location_name": info.get("location_name"),
+                                                       "version": info.get("version")},
+                           choices={"targets": targets})
+
+    async def send(self, req: AccessRequest, agent: Agent, links: dict[str, str], buttons: list[str]) -> None:
+        targets = self.config.get("targets") or []
+        if not targets:
+            raise RuntimeError("Home Assistant driver has no notify targets selected")
+        title, body = request_summary(req, agent)
+        from ..approvals import SCOPE_LABELS, notification_action
+
+        # Compact action IDs are authenticated; knowledge of a request ID grants no authority.
+        actions = [
+            {"action": notification_action(req.id, s), "title": SCOPE_LABELS[s], "destructive": s == "deny"}
+            for s in self.capped(buttons)
+        ]
+        open_url = links.get("once", "").rsplit("/d/", 1)[0] + f"/ui/requests/{req.id}"
+        data: dict[str, Any] = {
+            "tag": req.id,
+            "group": "keywright",
+            "actions": actions,
+            "url": open_url,
+            "clickAction": open_url,
+            # Android: survive swipes and stay put until decided or expired (the server clears it).
+            "persistent": True,
+            "sticky": True,
+            # iOS: show it even while the companion app is in the foreground.
+            "presentation_options": ["alert", "sound", "badge"],
+        }
+        if self.config.get("critical"):
+            data["push"] = {"interruption-level": "time-sensitive", "sound": "default"}
+            data["ttl"] = 0
+            data["priority"] = "high"
+        payload = {"title": title, "message": body, "data": data}
+        async with httpx.AsyncClient(timeout=15, headers=self._headers()) as c:
+            for t in targets:
+                r = await c.post(f"{self._base()}/api/services/notify/{t}", json=payload)
+                if r.status_code >= 400:
+                    log.error("HA notify.%s failed: %s %s", t, r.status_code, r.text[:200])
+
+    async def send_nudge(self, nudge: Nudge, agent: Agent, url: str) -> None:
+        targets = self.config.get("targets") or []
+        if not targets:
+            raise RuntimeError("Home Assistant driver has no notify targets selected")
+        from ..nudges import dismiss_action
+
+        title, body = nudge_summary(nudge, agent)
+        # Nothing here is a decision, so the only button clears the card; tapping the body opens
+        # the dashboard. Not marked critical even when approvals are: a question can wait for the
+        # next time they look at their phone, a destructive command cannot.
+        data: dict[str, Any] = {
+            "tag": nudge.id,
+            "group": "keywright-attention",
+            "actions": [{"action": dismiss_action(nudge.id), "title": "Dismiss"}],
+            "url": url,
+            "clickAction": url,
+            "persistent": True,
+            "sticky": True,
+            "presentation_options": ["alert", "sound", "badge"],
+        }
+        payload = {"title": title, "message": body, "data": data}
+        async with httpx.AsyncClient(timeout=15, headers=self._headers()) as c:
+            for t in targets:
+                r = await c.post(f"{self._base()}/api/services/notify/{t}", json=payload)
+                if r.status_code >= 400:
+                    log.error("HA notify.%s failed: %s %s", t, r.status_code, r.text[:200])
+
+    async def clear(self, req: AccessRequest) -> None:
+        await self._clear_tag(req.id)
+
+    async def clear_nudge(self, nudge: Nudge) -> None:
+        await self._clear_tag(nudge.id)
+
+    async def _clear_tag(self, tag: str) -> None:
+        payload = {"message": "clear_notification", "data": {"tag": tag}}
+        with contextlib.suppress(Exception):
+            async with httpx.AsyncClient(timeout=10, headers=self._headers()) as c:
+                for t in self.config.get("targets") or []:
+                    await c.post(f"{self._base()}/api/services/notify/{t}", json=payload)
+
+    async def start(self, on_decision: DecisionCallback) -> None:
+        self._stop.clear()
+        self._task = asyncio.create_task(self._listen(on_decision), name="ha-ws-listener")
+
+    async def stop(self) -> None:
+        self._stop.set()
+        if self._task:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await self._task
+            self._task = None
+
+    async def _listen(self, on_decision: DecisionCallback) -> None:
+        backoff = 2
+        while not self._stop.is_set():
+            try:
+                async with websockets.connect(self._ws_url(), max_size=2**20) as ws:
+                    hello = json.loads(await ws.recv())
+                    if hello.get("type") != "auth_required":
+                        raise RuntimeError(f"unexpected hello {hello}")
+                    await ws.send(json.dumps({"type": "auth", "access_token": self.config.get("token", "")}))
+                    resp = json.loads(await ws.recv())
+                    if resp.get("type") != "auth_ok":
+                        log.error("HA websocket auth failed: %s", resp)
+                        await asyncio.sleep(60)
+                        continue
+                    await ws.send(json.dumps({"id": 1, "type": "subscribe_events",
+                                              "event_type": "mobile_app_notification_action"}))
+                    log.info("HA websocket listener connected to %s", self._base())
+                    backoff = 2
+                    async for raw in ws:
+                        msg = json.loads(raw)
+                        if msg.get("type") != "event":
+                            continue
+                        action = ((msg.get("event") or {}).get("data") or {}).get("action") or ""
+                        log.info("HA notification action received: %s", action[:24] + ("…" if len(action) > 24 else ""))
+                        if action.startswith((ACTION_PREFIX, "KW_", "KWN_")):
+                            try:
+                                await on_decision(action)
+                            except Exception:
+                                log.exception("decision callback failed")
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:  # noqa: BLE001
+                log.warning("HA websocket listener error: %s; retry in %ss", e, backoff)
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, 60)

keywright_server/notify/log.py

@@ -0,0 +1,30 @@
+"""Fallback driver: writes requests to the log. Decisions come from the admin UI."""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+from ..models import AccessRequest, Agent, Nudge
+from .base import Notifier, ProbeResult, nudge_summary, register, request_summary
+
+log = logging.getLogger("keywright.notify")
+
+
+@register
+class LogNotifier(Notifier):
+    id = "log"
+    label = "Log only (decide in the admin UI)"
+    description = "No push channel. Pending requests show on the dashboard."
+    fields: ClassVar[list] = []
+
+    async def probe(self) -> ProbeResult:
+        return ProbeResult(ok=True, message="Nothing to configure.")
+
+    async def send(self, req: AccessRequest, agent: Agent, links: dict[str, str], buttons: list[str]) -> None:
+        title, body = request_summary(req, agent)
+        log.warning("ACCESS REQUEST %s\n%s\n%s\ndecide: %s", req.id, title, body, links.get("once", "").rsplit("/", 1)[0])
+
+    async def send_nudge(self, nudge: Nudge, agent: Agent, url: str) -> None:
+        title, body = nudge_summary(nudge, agent)
+        log.warning("NEEDS YOU %s\n%s\n%s\nclear: %s", nudge.id, title, body, url)

keywright_server/notify/manager.py

@@ -0,0 +1,131 @@
+"""Owns the active notifier. Config lives in settings["notifications"] =
+{"driver": "<id>", "config": {...}, "buttons": ["once", "session", "deny"]}."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from typing import Any
+
+from .. import audit
+from ..db import session
+from ..models import AccessRequest, Agent, Nudge
+from ..settings_store import get as get_setting
+from . import registry
+from .base import Notifier
+
+log = logging.getLogger("keywright.notify")
+DEFAULT_BUTTONS = ["once", "session", "deny"]
+
+
+class NotifierManager:
+    def __init__(self) -> None:
+        self.active: Notifier | None = None
+        self.driver_id: str = "log"
+        self.buttons: list[str] = list(DEFAULT_BUTTONS)
+        self.last_error: str = ""
+
+    async def reload(self) -> None:
+        async with session() as db:
+            cfg = await get_setting(db, "notifications", {"driver": "log", "config": {}, "buttons": DEFAULT_BUTTONS})
+        await self._apply(cfg)
+
+    async def _apply(self, cfg: dict[str, Any]) -> None:
+        from ..approvals import PHONE_SCOPES
+        if self.active:
+            await self.active.stop()
+        self.driver_id = cfg.get("driver") or "log"
+        cls = registry.get(self.driver_id) or registry["log"]
+        self.active = cls(cfg.get("config") or {})
+        self.buttons = [b for b in (cfg.get("buttons") or DEFAULT_BUTTONS) if b in PHONE_SCOPES]
+        if "deny" not in self.buttons:
+            self.buttons.append("deny")
+        await self.active.start(self.on_decision_token)
+        log.info("notifier: %s", self.driver_id)
+
+    async def stop(self) -> None:
+        if self.active:
+            await self.active.stop()
+
+    async def notify_request(self, req: AccessRequest, agent: Agent) -> None:
+        if not self.active:
+            return
+        from ..approvals import decision_links, offered_scopes
+
+        scopes = offered_scopes(req)
+        links = decision_links(req.id, scopes)
+        try:
+            await self.active.send(req, agent, links, [b for b in self.buttons if b in scopes])
+            self.last_error = ""
+        except Exception as e:
+            self.last_error = f"{type(e).__name__}: {e}"
+            log.exception("notifier %s failed for %s", self.driver_id, req.id)
+            async with session() as db:
+                await audit.record(db, tool="notify", decision="error", agent=agent, patterns=list(req.patterns),
+                                   detail={"request_id": req.id, "driver": self.driver_id, "error": self.last_error})
+
+    async def request_decided(self, req: AccessRequest) -> None:
+        if self.active:
+            await self.active.clear(req)
+
+    async def notify_nudge(self, nudge: Nudge, agent: Agent) -> None:
+        """Push "the agent needs you". A driver that cannot carry one just logs it: the dashboard
+        card is created either way, so the ask is never lost because a channel is misconfigured."""
+        if not self.active:
+            return
+        from ..approvals import public_url
+
+        try:
+            await self.active.send_nudge(nudge, agent, f"{public_url()}/ui")
+            self.last_error = ""
+        except NotImplementedError:
+            log.info("notifier %s cannot carry nudges; %s is on the dashboard only", self.driver_id, nudge.id)
+        except Exception as e:
+            self.last_error = f"{type(e).__name__}: {e}"
+            log.exception("notifier %s failed for nudge %s", self.driver_id, nudge.id)
+            async with session() as db:
+                await audit.record(db, tool="notify", decision="error", agent=agent,
+                                   detail={"nudge_id": nudge.id, "driver": self.driver_id, "error": self.last_error})
+
+    async def nudge_cleared(self, nudge: Nudge) -> None:
+        if self.active:
+            with contextlib.suppress(Exception):
+                await self.active.clear_nudge(nudge)
+
+    async def on_decision_token(self, action: str) -> None:
+        """Accept authenticated compact actions or legacy signed tokens, never bare request IDs."""
+        from .. import nudges
+        from ..approvals import decide, parse_decision_token, parse_notification_action
+
+        if action.startswith(nudges.DISMISS):
+            nudge_id = nudges.parse_dismiss_action(action)
+            if not nudge_id:
+                log.warning("ignored unrecognised dismiss action from %s", self.driver_id)
+                return
+            async with session() as db:
+                await nudges.clear(db, nudge_id, via=self.driver_id)
+            log.info("nudge %s dismissed via %s", nudge_id, self.driver_id)
+            return
+        parsed = None
+        if action.startswith(("KW_", "GK_")):
+            parsed = parse_notification_action(action)
+        elif action.startswith("GK:"):
+            parsed = parse_decision_token(action[3:])
+        else:
+            parsed = parse_decision_token(action)
+        if not parsed:
+            log.warning("ignored unrecognised decision action from %s", self.driver_id)
+            return
+        request_id, scope = parsed
+        async with session() as db:
+            try:
+                req = await decide(db, request_id, scope, via=self.driver_id)
+            except (LookupError, ValueError) as e:
+                # A tap that could not be applied (unknown request, or a lease whose key the gateway
+                # would not mint) leaves the request pending; the dashboard says why.
+                log.warning("decision for request %s not applied: %s", request_id, e)
+                return
+        log.info("decision via %s: %s -> %s (%s)", self.driver_id, request_id, req.status, scope)
+
+
+manager = NotifierManager()

keywright_server/notify/webhook.py

@@ -0,0 +1,79 @@
+"""Generic webhook driver: POSTs the request as JSON. Works with ntfy, Pushover relays, n8n,
+Slack incoming webhooks via a small template, or anything that can render links."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import httpx
+
+from ..models import AccessRequest, Agent, Nudge
+from .base import Field, Notifier, ProbeResult, nudge_summary, register, request_summary
+
+
+@register
+class WebhookNotifier(Notifier):
+    id = "webhook"
+    label = "Webhook (JSON POST)"
+    description = "POST {title, body, request, links} to a URL. Humans decide via the signed links."
+    fields: ClassVar[list[Field]] = [
+        Field("url", "Webhook URL", "url", required=True),
+        Field("auth_header", "Authorization header value", "password", help="Optional, sent as-is."),
+        Field("format", "Payload format", "select", options=[("json", "Keywright JSON"), ("ntfy", "ntfy.sh")]),
+    ]
+
+    async def probe(self) -> ProbeResult:
+        url = self.config.get("url", "")
+        if not url.startswith(("http://", "https://")):
+            return ProbeResult(ok=False, message="URL must start with http:// or https://")
+        return ProbeResult(ok=True, message="Saved. A test POST is sent on the first request.")
+
+    async def send(self, req: AccessRequest, agent: Agent, links: dict[str, str], buttons: list[str]) -> None:
+        from ..approvals import SCOPE_LABELS
+
+        title, body = request_summary(req, agent)
+        headers = {}
+        if self.config.get("auth_header"):
+            headers["Authorization"] = self.config["auth_header"]
+        if self.config.get("format") == "ntfy":
+            # ntfy rejects the whole message with a 400 when it carries more than three actions.
+            shown = self.capped([s for s in buttons if s in links])
+            actions = ", ".join(f"view, {SCOPE_LABELS[s]}, {links[s]}" for s in shown)
+            headers.update({"Title": title, "Actions": actions, "Tags": "lock"})
+            payload = body.encode()
+            async with httpx.AsyncClient(timeout=10) as c:
+                (await c.post(self.config["url"], content=payload, headers=headers)).raise_for_status()
+            return
+        payload = {
+            "title": title,
+            "body": body,
+            "request": {
+                "id": req.id, "agent": agent.name, "patterns": req.patterns, "reason": req.reason,
+                "detail": req.detail, "created_at": req.created_at.isoformat(),
+            },
+            "links": links,
+        }
+        async with httpx.AsyncClient(timeout=10) as c:
+            (await c.post(self.config["url"], json=payload, headers=headers)).raise_for_status()
+
+    async def send_nudge(self, nudge: Nudge, agent: Agent, url: str) -> None:
+        title, body = nudge_summary(nudge, agent)
+        headers = {}
+        if self.config.get("auth_header"):
+            headers["Authorization"] = self.config["auth_header"]
+        if self.config.get("format") == "ntfy":
+            headers.update({"Title": title, "Actions": f"view, Open dashboard, {url}", "Tags": "speech_balloon"})
+            async with httpx.AsyncClient(timeout=10) as c:
+                (await c.post(self.config["url"], content=body.encode(), headers=headers)).raise_for_status()
+            return
+        payload = {
+            "title": title,
+            "body": body,
+            "nudge": {
+                "id": nudge.id, "agent": agent.name, "message": nudge.message, "context": nudge.context,
+                "session": nudge.session_id, "created_at": nudge.created_at.isoformat(),
+            },
+            "links": {"open": url},
+        }
+        async with httpx.AsyncClient(timeout=10) as c:
+            (await c.post(self.config["url"], json=payload, headers=headers)).raise_for_status()