polyrob 0.5.0__py3-none-any.whl

core/surfaces/inbound_webhook.py

@@ -0,0 +1,124 @@
+"""WebhookSurface: the shared inbound contract for push-based platforms (WhatsApp,
+BlueBubbles, Telegram-webhook). Owns: signature verify -> fast-200 ack -> parse -> dedup ->
+route -> act. A concrete surface implements only verify/parse/idempotency_key. Fail-open
+end to end: a parse/route fault is logged, never raised to the HTTP layer (so the platform
+gets its 200 and does not retry-storm)."""
+import json
+import logging
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from core.surfaces.envelopes import InboundMessage
+from core.surfaces.idempotency import IdempotencyStore
+from core.surfaces.dispatcher import route_inbound
+from core.surfaces.serialize import KeyedLock
+from core.surfaces.session_chat_registry import build_session_key
+from core.surfaces.transcription import voice_present, transcribe_inbound_media
+from core.surfaces.voice_guard import voice_needs_guard, voice_unavailable_message
+from core.surfaces.voice_echo import voice_transcript, voice_echo_message
+from agents.task.surface_config import SurfaceConfig
+from surfaces.telegram.harness import act_on_inbound  # shared RouteDecision->TaskAgent dispatch
+from surfaces.telegram.inbound import InboundResult   # dataclass(.inbound, .decision) — DRY
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookSurface(ABC):
+    def __init__(self, idempotency: IdempotencyStore) -> None:
+        self._idem = idempotency
+        self._lock = KeyedLock()
+
+    @property
+    @abstractmethod
+    def surface_id(self) -> str: ...
+
+    @abstractmethod
+    def verify_signature(self, headers: dict, body: bytes) -> bool: ...
+
+    def verify_challenge(self, params: dict) -> Optional[str]:
+        """GET verification handshake (e.g. Meta hub.challenge). Default: no handshake."""
+        return None
+
+    @abstractmethod
+    def parse(self, payload: dict) -> List[InboundMessage]: ...
+
+    @abstractmethod
+    def idempotency_key(self, inbound: InboundMessage) -> str: ...
+
+    async def handle_post(self, container, headers: dict, body: bytes, task_agent) -> dict:
+        # Lower-case header keys so callers can pass platform headers verbatim.
+        h = {str(k).lower(): v for k, v in (headers or {}).items()}
+        if not self.verify_signature(h, body):
+            logger.warning("%s webhook: signature verification FAILED", self.surface_id)
+            return {"ok": False, "error": "bad signature"}
+        try:
+            payload = json.loads(body or b"{}")
+        except Exception as e:
+            logger.warning("%s webhook: bad JSON: %s", self.surface_id, e)
+            return {"ok": True}      # ack so the platform stops retrying garbage
+        try:
+            messages = self.parse(payload)
+        except Exception as e:
+            logger.error("%s webhook: parse failed: %s", self.surface_id, e, exc_info=True)
+            return {"ok": True}
+        for inbound in messages:
+            try:
+                key = self.idempotency_key(inbound)
+                if key and self._idem.seen(key):
+                    continue
+                session_key = build_session_key(inbound.identity.source, inbound.identity.user_id)
+                async with self._lock.for_key(session_key):
+                    # Fix 2b: hydrate surface-specific media (e.g. WA media-id -> bytes) before transcription
+                    if hasattr(self, "hydrate_media"):
+                        try:
+                            await self.hydrate_media(inbound.media)
+                        except Exception:
+                            pass
+                    # Fix 2a: transcribe voice-only turns; guard untranscribed voice (never route empty)
+                    if voice_present(inbound.media) and not (inbound.text or "").strip():
+                        try:
+                            _vtext = await transcribe_inbound_media(container, inbound.media)
+                        except Exception:
+                            _vtext = None
+                        if _vtext:
+                            inbound.text = _vtext
+                            for _m in inbound.media:
+                                if getattr(_m, "kind", None) in ("voice", "audio"):
+                                    _m.transcript = _vtext
+                                    break
+                    if voice_needs_guard(inbound.media, inbound.text):
+                        await self._send_immediate(
+                            inbound,
+                            voice_unavailable_message(SurfaceConfig.voice_transcription_enabled()),
+                        )
+                        continue
+                    # Persistent transcript echo (voice only) — see core.surfaces.voice_echo.
+                    # Lands before the agent runs; fail-open (never blocks the turn).
+                    if SurfaceConfig.voice_transcript_echo_enabled():
+                        _t = voice_transcript(inbound.media)
+                        if _t:
+                            try:
+                                await self._send_immediate(
+                                    inbound, voice_echo_message(_t),
+                                    reply_to=inbound.idempotency_key)
+                            except Exception as e:
+                                logger.debug("%s transcript echo failed: %s", self.surface_id, e)
+                            _mr = getattr(self, "mark_read_inbound", None)
+                            if _mr is not None:
+                                try:
+                                    await _mr(inbound)
+                                except Exception:
+                                    pass
+                    decision = await route_inbound(container, inbound)
+                    result = InboundResult(inbound=inbound, decision=decision)
+                    reply = await act_on_inbound(task_agent, result)
+                    if reply:
+                        await self._send_immediate(inbound, reply)
+            except Exception as e:  # fail-open per message
+                logger.error("%s webhook: process failed: %s", self.surface_id, e, exc_info=True)
+        return {"ok": True}
+
+    async def _send_immediate(self, inbound: InboundMessage, text: str, reply_to=None) -> None:
+        """Deliver a synchronous reply (DENIED notice / command ack / transcript echo).
+        Override per surface. ``reply_to`` optionally quotes the inbound message."""
+        logger.debug("%s immediate reply suppressed (no transport): %s", self.surface_id, text[:80])

core/surfaces/media.py

@@ -0,0 +1,32 @@
+"""Typed media envelope shared by every surface. Inbound media (voice/image/doc) is
+normalized to Media so the core transcription/handling seams are transport-agnostic.
+Kept intentionally small: bytes XOR url; a surface fills whichever it has cheaply."""
+from dataclasses import dataclass
+from typing import List, Optional
+
+_KINDS = {"voice", "audio", "image", "video", "document", "sticker"}
+
+
+@dataclass
+class Media:
+    kind: str
+    mime: Optional[str] = None
+    data: Optional[bytes] = None
+    url: Optional[str] = None
+    caption: Optional[str] = None
+    filename: Optional[str] = None
+    transcript: Optional[str] = None
+
+
+def coerce_media(items: list) -> List[Media]:
+    out: List[Media] = []
+    for it in items or []:
+        if isinstance(it, Media):
+            out.append(it)
+        elif isinstance(it, dict) and it.get("kind") in _KINDS:
+            out.append(Media(
+                kind=it["kind"], mime=it.get("mime"), data=it.get("data"),
+                url=it.get("url"), caption=it.get("caption"), filename=it.get("filename"),
+                transcript=it.get("transcript"),
+            ))
+    return out

core/surfaces/message_router.py

@@ -0,0 +1,91 @@
+"""MessageRouter: the SINGLE outbound producer seam.
+
+Every agent->user emit funnels through publish(). Text is brain-scrubbed here
+(SSOT = modules.llm.brain_scrubber) so every surface inherits the scrub. Surfaces
+subscribe by surface_id; routing resolves session_key -> surface_id via the
+SessionChatRegistry. Fail-open: an unroutable key or a raising surface never
+crashes the agent loop.
+"""
+import logging
+
+from core.surfaces.envelopes import OutboundMessage
+from core.surfaces.session_chat_registry import SessionChatRegistry
+from modules.llm.brain_scrubber import scrub_brain_blocks
+
+logger = logging.getLogger(__name__)
+
+
+class MessageRouter:
+    def __init__(self, registry: SessionChatRegistry) -> None:
+        self._registry = registry
+        self._surfaces: dict[str, object] = {}
+        self._queue = None
+
+    def attach_queue(self, q) -> None:
+        """Attach a durable OutboundDeliveryQueue. Call from bootstrap after construction."""
+        self._queue = q
+
+    def subscribe(self, surface_id: str, surface) -> None:
+        self._surfaces[surface_id] = surface
+
+    async def publish(self, msg: OutboundMessage) -> None:
+        try:
+            scrubbed = scrub_brain_blocks(msg.text)
+        except Exception:  # fail-open: never drop a reply over a scrub bug
+            scrubbed = msg.text
+        # F3 parity with HITLManager.stream_output: a wholly-brain (or empty) chunk
+        # scrubs to None/"" and must be DROPPED, not delivered as an empty bubble.
+        if scrubbed is None or not scrubbed.strip():
+            return
+        if scrubbed != msg.text:
+            msg = OutboundMessage(
+                session_key=msg.session_key, text=scrubbed, kind=msg.kind,
+                partial=msg.partial, stream_id=msg.stream_id,
+                reply_to=msg.reply_to, media=msg.media,
+            )
+        row = self._registry.resolve(msg.session_key)
+        if not row:
+            logger.debug("message_router: no binding for %s; dropping", msg.session_key)
+            return
+        surface = self._surfaces.get(row.get("surface_id"))
+        if surface is None:
+            logger.debug("message_router: no surface %s subscribed", row.get("surface_id"))
+            return
+        # Durable path (final messages only): enqueue instead of sending directly.
+        from agents.task.surface_config import SurfaceConfig
+        if (self._queue is not None and not msg.partial
+                and SurfaceConfig.outbound_queue_enabled()):
+            turn = msg.stream_id or msg.session_key
+            idem = f"{msg.session_key}#{turn}#{hash(scrubbed) & 0xffffffff}"
+            try:
+                self._queue.enqueue(
+                    idempotency_key=idem, session_key=msg.session_key,
+                    surface_id=row.get("surface_id"), dest=row.get("chat_id"),
+                    payload=scrubbed, kind=str(getattr(msg.kind, "value", msg.kind)),
+                )
+            except Exception as e:  # fail-open: fall back to a direct send on a queue fault
+                logger.error("outbound enqueue failed, sending directly: %s", e)
+            else:
+                return
+        try:
+            if msg.partial:
+                await surface.stream(msg)  # base buffers if surface can't stream
+            else:
+                await surface.send(msg)
+        except Exception as e:  # fail-open
+            logger.error("message_router: surface %s raised: %s", row.get("surface_id"), e, exc_info=True)
+
+    async def send_message(self, chat_id: str, text: str, surface_id: str = "telegram") -> bool:
+        """Back-compat shim for cron/delivery.py. Returns True only on a completed send."""
+        surface = self._surfaces.get(surface_id)
+        if surface is None:
+            logger.warning("send_message: no surface %s registered — delivery failed", surface_id)
+            return False
+        try:
+            await surface.send(OutboundMessage(
+                session_key=f"direct:{surface_id}:{chat_id}", text=text,
+            ))
+            return True
+        except Exception as e:
+            logger.error("send_message shim failed: %s", e, exc_info=True)
+            return False

core/surfaces/outbound_allowlist.py

@@ -0,0 +1,80 @@
+"""Owner-scoped outbound send-authorization. Default-DENY: a (user_id, surface,
+target) must have an ACTIVE row to be sendable. Owner targets bypass this (resolved
+upstream in outbound_target.resolve_target_tier). Tenant-scoped, WAL+jitter via
+``core/sqlite_util`` (no hand-rolled retry loop) — mirrors ``agents/task/goals/board.py``.
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Dict, List
+
+from core.sqlite_util import execute_retry
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS outbound_allowlist (
+    user_id TEXT NOT NULL,
+    surface TEXT NOT NULL,
+    target  TEXT NOT NULL,
+    note    TEXT NOT NULL DEFAULT '',
+    status  TEXT NOT NULL DEFAULT 'active',
+    created_at REAL NOT NULL,
+    PRIMARY KEY (user_id, surface, target)
+);
+"""
+
+
+class OutboundAllowlist:
+    def __init__(self, db_path: str) -> None:
+        self.db_path = db_path
+        parent = os.path.dirname(db_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        execute_retry(self.db_path, _DDL)
+
+    def allow(self, user_id: str, surface: str, target: str, note: str = "") -> None:
+        execute_retry(
+            self.db_path,
+            "INSERT INTO outbound_allowlist(user_id,surface,target,note,status,created_at)"
+            " VALUES(?,?,?,?, 'active', ?)"
+            " ON CONFLICT(user_id,surface,target) DO UPDATE SET status='active', note=excluded.note",
+            (user_id, surface, target, note, time.time()),
+        )
+
+    def revoke(self, user_id: str, surface: str, target: str) -> bool:
+        rc = execute_retry(
+            self.db_path,
+            "UPDATE outbound_allowlist SET status='revoked'"
+            " WHERE user_id=? AND surface=? AND target=? AND status='active'",
+            (user_id, surface, target),
+        )
+        return bool(rc)
+
+    def is_allowed(self, user_id: str, surface: str, target: str) -> bool:
+        row = execute_retry(
+            self.db_path,
+            "SELECT 1 FROM outbound_allowlist"
+            " WHERE user_id=? AND surface=? AND target=? AND status='active'",
+            (user_id, surface, target),
+            fetch="one",
+        )
+        return row is not None
+
+    def list(self, user_id: str) -> List[Dict]:
+        rows = execute_retry(
+            self.db_path,
+            "SELECT surface,target,note,status,created_at FROM outbound_allowlist"
+            " WHERE user_id=? ORDER BY created_at DESC",
+            (user_id,),
+            fetch="all",
+        ) or []
+        return [
+            {
+                "surface": r["surface"],
+                "target": r["target"],
+                "note": r["note"],
+                "status": r["status"],
+                "created_at": r["created_at"],
+            }
+            for r in rows
+        ]

core/surfaces/outbound_dispatcher.py

@@ -0,0 +1,110 @@
+"""Drains OutboundDeliveryQueue: per-dest token-bucket pace, send via the surface, backoff
+on failure, dead-letter after max_attempts. Deterministic backoff base (jitter added only
+in the live run loop, not drain_once, so tests are reproducible)."""
+import asyncio
+import logging
+import random
+from typing import Callable, Optional
+
+from core.surfaces.envelopes import OutboundMessage
+from core.surfaces.outbound_queue import OutboundDeliveryQueue
+from core.surfaces.rate_bucket import TokenBucket
+
+logger = logging.getLogger(__name__)
+
+# TYPE_CHECKING import avoids a circular-import risk; the breaker is pure.
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from core.surfaces.circuit import SurfaceCircuitBreaker
+
+
+class OutboundDispatcher:
+    def __init__(self, queue: OutboundDeliveryQueue,
+                 surface_lookup: Callable[[str], Optional[object]], *,
+                 max_attempts: int = 6, base_backoff: float = 2.0,
+                 rate_per_sec: float = 20.0, burst: int = 20,
+                 circuit: Optional["SurfaceCircuitBreaker"] = None) -> None:
+        self._q = queue
+        self._lookup = surface_lookup
+        self._max = max_attempts
+        self._base = base_backoff
+        self._bucket = TokenBucket(rate_per_sec, burst)
+        self._cb = circuit   # SurfaceCircuitBreaker | None
+        self._task: Optional[asyncio.Task] = None
+        self._stop = asyncio.Event()
+
+    async def drain_once(self, now: float) -> int:
+        delivered = 0
+        for row in self._q.claim_due(now):
+            surface_id = row["surface_id"]
+
+            # --- Circuit breaker: skip open surfaces; defer 30 s, attempts unchanged ---
+            if self._cb is not None and self._cb.is_open(surface_id):
+                self._q.reschedule(row["id"], next_attempt_at=now + 30,
+                                   attempts=row["attempts"])
+                logger.debug("outbound circuit OPEN: surface=%s deferred 30s", surface_id)
+                continue
+
+            key = f"{surface_id}:{row['dest']}"
+            allowed, retry_after = self._bucket.take(key, now=now)
+            if not allowed:
+                self._q.reschedule(row["id"], next_attempt_at=now + retry_after,
+                                   attempts=row["attempts"])
+                continue
+            surface = self._lookup(surface_id)
+            ok, err = False, "no surface"
+            if surface is not None:
+                try:
+                    res = await surface.send(OutboundMessage(
+                        session_key=row["session_key"], text=row["payload"],
+                    ))
+                    ok = bool(getattr(res, "success", False))
+                    err = getattr(res, "error", None) or ("ok" if ok else "send returned False")
+                except Exception as exc:  # fail-open: a raising surface reschedules, never crashes
+                    ok, err = False, str(exc)
+            if ok:
+                if self._cb is not None:
+                    self._cb.record_ok(surface_id)
+                self._q.mark_delivered(row["id"])
+                delivered += 1
+            else:
+                if self._cb is not None:
+                    self._cb.record_fail(surface_id)
+                attempts = row["attempts"] + 1
+                if attempts >= self._max:
+                    self._q.dead_letter(row["id"], err)
+                    logger.error("outbound DEAD-LETTER id=%s surface=%s dest=%s err=%s",
+                                 row["id"], surface_id, row["dest"], err)
+                else:
+                    backoff = self._base * (2 ** (attempts - 1))
+                    self._q.reschedule(row["id"], next_attempt_at=now + backoff,
+                                       attempts=attempts, error=err)
+        return delivered
+
+    async def run(self, interval: float = 1.0) -> None:
+        import time as _t
+        while not self._stop.is_set():
+            try:
+                now_ts = _t.time()
+                if now_ts - getattr(self, "_last_reclaim", 0) > 60:
+                    self._q.reclaim_inflight(older_than=now_ts - 120)
+                    self._last_reclaim = now_ts
+                await self.drain_once(now=now_ts + random.uniform(0, 0.05))
+            except Exception as exc:
+                logger.error("outbound dispatcher loop error: %s", exc, exc_info=True)
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=interval)
+            except asyncio.TimeoutError:
+                pass
+
+    def start(self) -> None:
+        if self._task is None:
+            self._task = asyncio.ensure_future(self.run())
+
+    async def stop(self) -> None:
+        self._stop.set()
+        if self._task is not None:
+            try:
+                await asyncio.wait_for(self._task, timeout=5.0)
+            except Exception:
+                self._task.cancel()

core/surfaces/outbound_mirror.py

@@ -0,0 +1,37 @@
+"""Outbound-collapse mirror helpers (P1a).
+
+Small factories that mirror an agent's discrete user-facing message into the
+unified MessageRouter seam as a committed (partial=False) OutboundMessage. Additive
+and gated on SINGULAR_CHAT_ENABLED; a no-op (and fail-open) when the flag is OFF or
+no router / session_key has been bound, so the legacy add_to_feed path stays
+byte-identical until later phases wire a router.
+"""
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def build_discrete_publish(
+    router: Any, session_key: Optional[str]
+) -> Callable[..., Awaitable[None]]:
+    async def _publish(text: str) -> None:
+        from agents.task.surface_config import SurfaceConfig
+
+        if not SurfaceConfig.singular_chat_enabled():
+            return
+        if router is None or not session_key:
+            return
+        try:
+            from core.surfaces.envelopes import OutboundMessage, MessageKind
+
+            await router.publish(OutboundMessage(
+                session_key=session_key,
+                text=text,
+                kind=MessageKind.AGENT_TEXT,
+                partial=False,
+            ))
+        except Exception as e:  # fail-open: outbound mirror is non-critical
+            logger.debug("discrete publish mirror failed: %s", e)
+
+    return _publish

core/surfaces/outbound_queue.py

@@ -0,0 +1,107 @@
+"""Durable outbound delivery queue (SQLite WAL). Converts MessageRouter's fire-and-forget
+send into at-least-once-with-dedup: publish() enqueues; a dispatcher worker drains with
+backoff + token-bucket, dead-lettering after N attempts. idempotency_key (hash of
+session_key+turn_id+chunk_idx) dedups a redelivery after a worker crash."""
+import logging
+import time as _time
+from typing import List, Optional
+
+from core.sqlite_util import wal_connect, execute_retry
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS outbound_queue (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    idempotency_key TEXT UNIQUE,
+    session_key     TEXT NOT NULL,
+    surface_id      TEXT NOT NULL,
+    dest            TEXT,
+    payload         TEXT NOT NULL,
+    kind            TEXT DEFAULT 'agent_text',
+    state           TEXT DEFAULT 'pending',   -- pending|inflight|delivered|dead
+    attempts        INTEGER DEFAULT 0,
+    next_attempt_at REAL DEFAULT 0,
+    last_error      TEXT,
+    created_at      REAL DEFAULT (strftime('%s','now')),
+    updated_at      REAL DEFAULT (strftime('%s','now'))
+)
+"""
+
+
+class OutboundDeliveryQueue:
+    def __init__(self, db_path: str) -> None:
+        self.db_path = db_path
+        conn = wal_connect(db_path)
+        try:
+            conn.execute(_SCHEMA)
+            conn.commit()
+        finally:
+            conn.close()
+
+    def enqueue(self, *, idempotency_key: str, session_key: str, surface_id: str,
+                dest: Optional[str], payload: str, kind: str = "agent_text") -> bool:
+        inserted = execute_retry(
+            self.db_path,
+            """INSERT OR IGNORE INTO outbound_queue
+                 (idempotency_key, session_key, surface_id, dest, payload, kind, next_attempt_at)
+               VALUES (?, ?, ?, ?, ?, ?, 0)""",
+            (idempotency_key, session_key, surface_id, dest, payload, kind),
+        )
+        return inserted == 1
+
+    def claim_due(self, now: float, limit: int = 20) -> List[dict]:
+        # Two-step claim under WAL: select due ids, then CAS each to 'inflight'.
+        rows = execute_retry(
+            self.db_path,
+            """SELECT * FROM outbound_queue
+               WHERE state='pending' AND next_attempt_at <= ?
+               ORDER BY id ASC LIMIT ?""",
+            (now, limit), fetch="all",
+        ) or []
+        claimed = []
+        for r in rows:
+            n = execute_retry(
+                self.db_path,
+                "UPDATE outbound_queue SET state='inflight', updated_at=? WHERE id=? AND state='pending'",
+                (now, r["id"]),
+            )
+            if n == 1:
+                d = dict(r); d["state"] = "inflight"; claimed.append(d)
+        return claimed
+
+    def mark_delivered(self, row_id: int) -> None:
+        execute_retry(self.db_path,
+                      "UPDATE outbound_queue SET state='delivered', updated_at=? WHERE id=?",
+                      (_time.time(), row_id))
+
+    def reschedule(self, row_id: int, *, next_attempt_at: float, attempts: int,
+                   error: Optional[str] = None) -> None:
+        execute_retry(
+            self.db_path,
+            """UPDATE outbound_queue SET state='pending', attempts=?, next_attempt_at=?,
+                 last_error=?, updated_at=? WHERE id=?""",
+            (attempts, next_attempt_at, error, _time.time(), row_id),
+        )
+
+    def dead_letter(self, row_id: int, error: str) -> None:
+        execute_retry(self.db_path,
+                      "UPDATE outbound_queue SET state='dead', last_error=?, updated_at=? WHERE id=?",
+                      (error, _time.time(), row_id))
+
+    def counts(self) -> dict:
+        rows = execute_retry(self.db_path,
+                             "SELECT state, COUNT(*) c FROM outbound_queue GROUP BY state",
+                             fetch="all") or []
+        out = {"pending": 0, "inflight": 0, "delivered": 0, "dead": 0}
+        for r in rows:
+            out[r["state"]] = r["c"]
+        return out
+
+    def reclaim_inflight(self, older_than: float) -> int:
+        """Restart-recovery: return long-inflight rows to 'pending' (a worker died mid-send)."""
+        return execute_retry(
+            self.db_path,
+            "UPDATE outbound_queue SET state='pending' WHERE state='inflight' AND updated_at < ?",
+            (older_than,),
+        ) or 0

core/surfaces/outbound_target.py

@@ -0,0 +1,12 @@
+"""Pure resolver: is this outbound target the owner, an allowlisted party, or denied?
+Owner-address map is injected (from core/instance resolvers at the call site) so this
+stays pure and unit-testable."""
+
+def resolve_target_tier(*, surface: str, target: str, user_id: str, allowlist,
+                        owner_targets: dict) -> str:
+    owner_addr = (owner_targets or {}).get(surface)
+    if owner_addr is not None and str(target) == str(owner_addr):
+        return "owner"
+    if allowlist is not None and allowlist.is_allowed(user_id, surface, target):
+        return "allowlisted"
+    return "denied"

core/surfaces/owner_admin.py

@@ -0,0 +1,29 @@
+"""WS-D: owner/access quick-access — one read of the access SSOT.
+
+A single place that reports who the agent serves and the per-surface access posture, so
+the `polyrob owner` CLI (and any admin surface) doesn't re-derive it from scattered
+flags. Owner-by-email is reported as a hard OFF in v1 (a forgeable From: can never
+confer OWNER tier until verified-sender lands).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def owner_access_summary() -> Dict[str, Any]:
+    from core.instance import resolve_owner_principal
+    from agents.task.surface_config import SurfaceConfig
+    return {
+        # STRICT: report only an EXPLICITLY-bound owner (None = running on the
+        # auto-derived instance-id default), so the summary reflects real config.
+        "owner_principal": resolve_owner_principal(default_to_instance=False),
+        "correspondent_access_enabled": SurfaceConfig.correspondent_access_enabled(),
+        "require_approval": SurfaceConfig.correspondent_require_approval(),
+        "max_new_correspondents_per_day": SurfaceConfig.correspondent_max_new_per_day(),
+        "surfaces": {
+            "telegram": SurfaceConfig.telegram_surface_enabled(),
+            "whatsapp": SurfaceConfig.whatsapp_surface_enabled(),
+            "email": SurfaceConfig.email_surface_enabled(),
+        },
+        "owner_by_email": False,  # v1: hard OFF (forgeable From:)
+    }