polyrob 0.5.0__py3-none-any.whl

core/sqlite_util.py

@@ -0,0 +1,59 @@
+"""Small shared SQLite helper: WAL connection + jittered write-retry (roadmap P6).
+
+Centralizes the WAL-with-DELETE-fallback + 'database is locked' retry pattern so
+the cross-process session registry (and, later, the cron store) don't each
+re-implement it. Mirrors Reference ``SessionDB``: WAL for concurrent readers + one
+writer, DELETE fallback on NFS/SMB/FUSE, and 20–150ms jitter to avoid SQLite's
+deterministic backoff convoy under contention.
+"""
+from __future__ import annotations
+
+import random
+import sqlite3
+import time
+from typing import Optional
+
+_MAX_RETRIES = 15
+_BUSY_TIMEOUT_S = 1.0
+
+
+def wal_connect(db_path: str, timeout: float = _BUSY_TIMEOUT_S) -> sqlite3.Connection:
+    conn = sqlite3.connect(db_path, timeout=timeout)
+    conn.row_factory = sqlite3.Row
+    try:
+        conn.execute("PRAGMA journal_mode=WAL")
+    except sqlite3.OperationalError:
+        conn.execute("PRAGMA journal_mode=DELETE")
+    return conn
+
+
+def execute_retry(db_path: str, sql: str, params: tuple = (), *, fetch: Optional[str] = None):
+    """Execute one statement with jittered retry on write contention.
+
+    fetch: None -> rowcount; 'one' -> a Row or None; 'all' -> list[Row].
+    """
+    last_err: Optional[Exception] = None
+    for _ in range(_MAX_RETRIES):
+        try:
+            conn = wal_connect(db_path)
+            try:
+                cur = conn.execute(sql, params)
+                if fetch == "one":
+                    row = cur.fetchone()
+                    conn.commit()
+                    return row
+                if fetch == "all":
+                    rows = cur.fetchall()
+                    conn.commit()
+                    return rows
+                conn.commit()
+                return cur.rowcount
+            finally:
+                conn.close()
+        except sqlite3.OperationalError as e:
+            if "locked" in str(e).lower() or "busy" in str(e).lower():
+                last_err = e
+                time.sleep(random.uniform(0.02, 0.15))
+                continue
+            raise
+    raise last_err  # type: ignore[misc]

core/surfaces/__init__.py

@@ -0,0 +1,16 @@
+"""Singular Chat Interface — transport-free surface contract (core)."""
+from core.surfaces.envelopes import (
+    MessageKind, SessionSource, Identity, InboundMessage,
+    OutboundMessage, SurfaceCapabilities, SendResult,
+)
+from core.surfaces.surface import Surface
+from core.surfaces.session_chat_registry import SessionChatRegistry, build_session_key
+from core.surfaces.message_router import MessageRouter
+from core.surfaces.registry import SurfaceRegistry, register_surface, is_surface_enabled
+
+__all__ = [
+    "MessageKind", "SessionSource", "Identity", "InboundMessage",
+    "OutboundMessage", "SurfaceCapabilities", "SendResult", "Surface",
+    "SessionChatRegistry", "build_session_key", "MessageRouter",
+    "SurfaceRegistry", "register_surface", "is_surface_enabled",
+]

core/surfaces/access.py

@@ -0,0 +1,118 @@
+"""WS-A access-tier resolver — classify one inbound's sender into a trust tier.
+
+Three tiers, resolved ONCE at the routing boundary and carried into the dispatcher:
+
+- **OWNER** — the bound owner principal, the local single-user operator, or a paired
+  user. May command the agent (steering turn).
+- **CORRESPONDENT** — a third party the agent INITIATED contact with, i.e. an ACTIVE
+  binding in the correspondent registry. Their inbound is DATA delivered only to the
+  originating session; it can never command the agent.
+- **DENIED** — anonymous, unknown, group/multi-party, or anything that isn't clearly
+  one of the above.
+
+Invariants:
+- **Tier = authenticated sender**, never thread membership (the registry keys on the
+  sender address; ``thread_id`` only disambiguates among that sender's own sessions).
+- **Fail-closed on the CORRESPONDENT→OWNER boundary**: any fault degrades toward
+  DENIED and never UPGRADES a sender to OWNER.
+- **Groups/channels are DENIED in v1** — the envelope is single-principal, so there is
+  no safe per-author tiering inside a multi-party chat yet.
+
+Pure decision function; no surface/transport imports. Reads ``POLYROB_LOCAL`` directly
+(like ``core/pairing``) to stay on the core side of the core→agents boundary.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from enum import Enum
+from typing import Any, Mapping, Optional
+
+logger = logging.getLogger(__name__)
+
+_BOOL_TRUE = {"1", "true", "yes", "on"}
+
+# Single-user local mode (`is_owner(local=True)`) grants OWNER to any non-empty uid.
+# That is correct ONLY for surfaces whose principal is the local operator — NEVER for a
+# network surface where the sender id is a forgeable remote address (Fusion CRITICAL:
+# else any email/telegram sender becomes an owner command-turn under POLYROB_LOCAL).
+_LOCAL_OWNER_SURFACES = {"cli", "local", "repl"}
+
+
+class AccessTier(str, Enum):
+    OWNER = "owner"
+    CORRESPONDENT = "correspondent"
+    DENIED = "denied"
+
+
+def _is_owner_or_paired(container: Any, uid: str, env: Mapping[str, str],
+                        *, allow_local: bool) -> bool:
+    """True if ``uid`` is the owner/local operator or a paired user. Fail-closed.
+
+    ``allow_local`` gates the single-user local-owner bypass: it is only honoured for a
+    trusted local surface (never a network surface — see ``_LOCAL_OWNER_SURFACES``).
+    """
+    try:
+        from core.instance import is_owner, resolve_owner_principal
+        local = allow_local and (env.get("POLYROB_LOCAL", "") or "").strip().lower() in _BOOL_TRUE
+        if is_owner(uid, owner_principal=resolve_owner_principal(env), local=local):
+            return True
+    except Exception as e:  # never let an owner-check fault grant or crash
+        logger.debug("access-tier owner check failed (fail-closed): %s", e)
+    try:
+        from core.pairing import PairingStore
+        cfg = getattr(container, "config", None) if container else None
+        data_dir = getattr(cfg, "data_dir", "data") or "data"
+        store = PairingStore(os.path.join(data_dir, "pairing.db"))
+        if store.is_paired(uid):
+            return True
+    except Exception as e:
+        logger.debug("access-tier pairing check failed (fail-closed): %s", e)
+    return False
+
+
+def resolve_access_tier(
+    container: Any,
+    identity: Any,
+    *,
+    thread_id: Optional[str] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> AccessTier:
+    """Classify ``identity`` into an :class:`AccessTier`. Never raises."""
+    src = os.environ if env is None else env
+    try:
+        uid = (str(getattr(identity, "user_id", "")) or "").strip()
+        if not uid:
+            return AccessTier.DENIED
+
+        source = getattr(identity, "source", None)
+        surface = getattr(source, "surface_id", "") or ""
+        chat_type = getattr(source, "chat_type", "dm") or "dm"
+
+        # v1: no per-author tiering inside a multi-party chat -> DENIED.
+        if chat_type != "dm":
+            return AccessTier.DENIED
+
+        if _is_owner_or_paired(container, uid, src,
+                               allow_local=surface in _LOCAL_OWNER_SURFACES):
+            return AccessTier.OWNER
+
+        # Non-owner: routable ONLY as a known correspondent (active binding).
+        registry = container.get_service("correspondent_registry") if container else None
+        if registry is not None:
+            address = getattr(identity, "raw_user_id", None) or uid
+            try:
+                row = registry.resolve(surface=surface, address=address, thread_id=thread_id)
+            except Exception as e:  # fail-closed: a registry fault is NOT an upgrade
+                logger.debug("access-tier registry resolve failed (fail-closed): %s", e)
+                row = None
+            if row is not None:
+                return AccessTier.CORRESPONDENT
+
+        return AccessTier.DENIED
+    except Exception as e:  # absolute fail-closed backstop
+        logger.debug("resolve_access_tier fault (fail-closed to DENIED): %s", e)
+        return AccessTier.DENIED
+
+
+__all__ = ["AccessTier", "resolve_access_tier"]

core/surfaces/binding.py

@@ -0,0 +1,88 @@
+"""P1b-2: bind a session's orchestrator to the Singular Chat outbound bus.
+
+Called from TaskAgent.create_session immediately after the orchestrator is built
+and BEFORE orchestrator.initialize() — because _register_stream_callback captures
+orchestrator._message_router / ._chat_session_key BY VALUE when it wires the stream
+mirror, so binding after initialize() would capture None (a permanent no-op).
+
+Flag-gated (SINGULAR_CHAT_ENABLED, default OFF) and fail-open: when OFF, or the bus
+isn't installed, or no chat_session_key was supplied (legacy callers: cron/goal/
+`polyrob run`/raw API), it touches NOTHING and returns False -> the orchestrator keeps
+its legacy callback-only path, byte-identical to today.
+"""
+import logging
+from typing import Any, Optional
+
+from core.surfaces.envelopes import SessionSource
+
+logger = logging.getLogger(__name__)
+
+
+def bind_chat_surface(
+    orchestrator: Any,
+    container: Any,
+    *,
+    session_source: Optional[SessionSource],
+    chat_session_key: Optional[str],
+    session_id: str,
+    user_id: str,
+) -> bool:
+    """Set the orchestrator's router+key and write the chat<->session registry row.
+
+    Returns True when the orchestrator was bound (router+key set), False when the
+    feature is off / unavailable / no key was supplied.
+    """
+    from agents.task.surface_config import SurfaceConfig
+
+    if not SurfaceConfig.singular_chat_enabled():
+        return False
+    if container is None or not chat_session_key:
+        return False
+    router = container.get_service("message_router")
+    if router is None:
+        return False
+
+    orchestrator._message_router = router
+    orchestrator._chat_session_key = chat_session_key
+
+    # Write the durable chat<->session row so publish can resolve key -> surface.
+    # Needs the SessionSource (surface_id/chat_id); without it we still bind the
+    # mirror but publish will fail-open-drop until a row exists.
+    if session_source is not None:
+        registry = container.get_service("session_chat_registry")
+        if registry is not None:
+            try:
+                registry.bind(
+                    chat_session_key, session_id, user_id,
+                    session_source.surface_id, session_source.chat_id,
+                )
+            except Exception as e:  # fail-open: a bind error must not break session create
+                logger.debug("bind_chat_surface registry.bind failed: %s", e)
+    return True
+
+
+def surface_ask_capability(orchestrator: Any) -> Optional[bool]:
+    """Can the surface bound to this orchestrator collect a reply (ask)?
+
+    Returns True/False when a surface is bound and its capability is known, or None
+    when nothing is bound / the bus is absent (the legacy, surface-agnostic case).
+    Used by the send_message action to avoid the wait_for_response deadlock: pausing
+    a session to wait for a reply on a surface that can't deliver one would hang it.
+    """
+    key = getattr(orchestrator, "_chat_session_key", None)
+    container = getattr(orchestrator, "container", None)
+    if not key or container is None:
+        return None
+    try:
+        registry = container.get_service("session_chat_registry")
+        row = registry.resolve(key) if registry is not None else None
+        if not row:
+            return None
+        surface_registry = container.get_service("surface_registry")
+        surface = surface_registry.get(row.get("surface_id")) if surface_registry else None
+        if surface is None:
+            return None
+        return bool(surface.capabilities.supports_interactive_ask)
+    except Exception as e:  # fail-open: unknown -> legacy behavior
+        logger.debug("surface_ask_capability failed: %s", e)
+        return None

core/surfaces/bootstrap.py

@@ -0,0 +1,78 @@
+"""P1b-0: construct + register the outbound bus on a DI container.
+
+This is the one prerequisite the rest of the Singular Chat Interface depends on:
+nothing else in the codebase instantiates MessageRouter / SessionChatRegistry, so
+without this call container.get_service("message_router") is always None and every
+P1a outbound mirror (plus cron/delivery.py's telegram sink) is silently inert.
+
+Gated on SINGULAR_CHAT_ENABLED so flag-OFF means the services never exist -> the
+mirrors stay no-ops -> behavior is byte-identical to today. Idempotent: a second
+call reuses the already-installed router so live surface subscriptions are never
+dropped. Fail-open: any construction error logs and returns False rather than
+breaking startup.
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def install_surface_bus(container, db_path: str = None) -> bool:
+    """Build SessionChatRegistry + MessageRouter and register them on ``container``.
+
+    Returns True if the bus is present on the container after the call (installed
+    now or already present), False if the flag is OFF or construction failed.
+
+    ``db_path`` defaults to ``<container.config.data_dir>/surfaces.db`` so the bus,
+    outbox, and circuit store follow POLYROB_DATA_DIR isolation instead of a hardcoded
+    ``./data`` inside the code tree. Pass an explicit path to override.
+    """
+    from agents.task.surface_config import SurfaceConfig
+
+    if not SurfaceConfig.singular_chat_enabled():
+        return False
+
+    # Idempotent: never clobber a live router (it holds surface subscriptions).
+    existing = container.get_service("message_router")
+    if existing is not None:
+        return True
+
+    if db_path is None:
+        import os as _os
+        data_dir = getattr(getattr(container, "config", None), "data_dir", "data") or "data"
+        db_path = _os.path.join(data_dir, "surfaces.db")
+
+    try:
+        from core.surfaces.session_chat_registry import SessionChatRegistry
+        from core.surfaces.message_router import MessageRouter
+
+        registry = SessionChatRegistry(db_path)
+        router = MessageRouter(registry)
+        container.register_service("session_chat_registry", registry)
+        container.register_service("message_router", router)
+
+        from core.surfaces.outbound_allowlist import OutboundAllowlist
+        container.register_service("outbound_allowlist", OutboundAllowlist(db_path))
+
+        if SurfaceConfig.outbound_queue_enabled():
+            import os
+            from core.surfaces.outbound_queue import OutboundDeliveryQueue
+            from core.surfaces.outbound_dispatcher import OutboundDispatcher
+            from core.surfaces.circuit import CircuitStore, SurfaceCircuitBreaker
+            q = OutboundDeliveryQueue(os.path.join(os.path.dirname(db_path) or ".", "outbox.db"))
+            q.reclaim_inflight(older_than=__import__("time").time() - 120)  # restart-recovery
+            router.attach_queue(q)
+            circuit_store = CircuitStore(
+                os.path.join(os.path.dirname(db_path) or ".", "surface_state.db")
+            )
+            circuit = SurfaceCircuitBreaker(store=circuit_store)
+            dispatcher = OutboundDispatcher(q, lambda sid: router._surfaces.get(sid),
+                                            circuit=circuit)
+            container.register_service("outbound_queue", q)
+            container.register_service("outbound_dispatcher", dispatcher)
+            container.register_service("surface_circuit_breaker", circuit)
+            logger.info("surface bus: durable outbound queue + dispatcher + circuit breaker constructed")
+        logger.info("surface bus installed (session_chat_registry + message_router)")
+        return True
+    except Exception as e:  # fail-open: a bus build error must not break startup
+        logger.error("install_surface_bus failed: %s", e, exc_info=True)
+        return False

core/surfaces/circuit.py

@@ -0,0 +1,168 @@
+"""Per-surface circuit breaker for the outbound dispatcher.
+
+Opens automatically after K consecutive failures (stops hammering a dead platform);
+also supports manual pause/resume so an operator can hold a surface while it's
+in maintenance. An optional CircuitStore persists the paused flag across processes
+so the CLI's `polyrob surface pause` is visible to the worker.
+
+No `from __future__ import annotations` — callers may introspect param annotations.
+"""
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitStore:
+    """Tiny SQLite-backed paused-flag store.
+
+    One table: surface_state(surface_id TEXT PK, paused INTEGER).
+    Reads/writes go through core.sqlite_util for WAL + jittered retry.
+    """
+
+    _CREATE = (
+        "CREATE TABLE IF NOT EXISTS surface_state "
+        "(surface_id TEXT PRIMARY KEY, paused INTEGER NOT NULL DEFAULT 0)"
+    )
+
+    def __init__(self, db_path: str) -> None:
+        self._db = db_path
+        from core.sqlite_util import wal_connect
+        conn = wal_connect(db_path)
+        try:
+            conn.execute(self._CREATE)
+            conn.commit()
+        finally:
+            conn.close()
+
+    def pause(self, surface_id: str) -> None:
+        from core.sqlite_util import execute_retry
+        execute_retry(
+            self._db,
+            "INSERT INTO surface_state(surface_id, paused) VALUES(?,1) "
+            "ON CONFLICT(surface_id) DO UPDATE SET paused=1",
+            (surface_id,),
+        )
+
+    def resume(self, surface_id: str) -> None:
+        from core.sqlite_util import execute_retry
+        execute_retry(
+            self._db,
+            "INSERT INTO surface_state(surface_id, paused) VALUES(?,0) "
+            "ON CONFLICT(surface_id) DO UPDATE SET paused=0",
+            (surface_id,),
+        )
+
+    def is_paused(self, surface_id: str) -> bool:
+        from core.sqlite_util import execute_retry
+        row = execute_retry(
+            self._db,
+            "SELECT paused FROM surface_state WHERE surface_id=?",
+            (surface_id,),
+            fetch="one",
+        )
+        return bool(row and row["paused"])
+
+    def list_all(self) -> list:
+        from core.sqlite_util import execute_retry
+        rows = execute_retry(
+            self._db,
+            "SELECT surface_id, paused FROM surface_state ORDER BY surface_id",
+            fetch="all",
+        )
+        return [{"surface_id": r["surface_id"], "paused": bool(r["paused"])} for r in (rows or [])]
+
+
+class SurfaceCircuitBreaker:
+    """Auto-pauses a surface after `threshold` consecutive failures.
+
+    In-memory state:
+    - ``_counts[surface_id]``: consecutive failure counter (resets on ok).
+    - ``_paused``: set of manually paused surface IDs.
+
+    Optional ``store`` (a ``CircuitStore``): pause/resume also writes the flag to
+    SQLite, and ``is_open`` reads it so a worker process sees CLI changes.
+    """
+
+    def __init__(self, threshold: int = 5, store: Optional[CircuitStore] = None) -> None:
+        self._threshold = threshold
+        self._counts: dict = {}   # surface_id -> consecutive fail count
+        self._paused: set = set()
+        self._store = store
+
+    # ------------------------------------------------------------------
+    # Auto-tripping path
+    # ------------------------------------------------------------------
+
+    def record_ok(self, surface_id: str) -> None:
+        """Reset the consecutive-fail counter; closes the auto-open state."""
+        self._counts[surface_id] = 0
+
+    def record_fail(self, surface_id: str) -> None:
+        """Increment the consecutive-fail counter; opens when >= threshold."""
+        count = self._counts.get(surface_id, 0) + 1
+        self._counts[surface_id] = count
+        if count >= self._threshold:
+            logger.warning(
+                "circuit_breaker: surface=%s opened after %d consecutive failures",
+                surface_id, count,
+            )
+
+    # ------------------------------------------------------------------
+    # Manual pause/resume path
+    # ------------------------------------------------------------------
+
+    def pause(self, surface_id: str) -> None:
+        """Manually pause a surface (operator-driven; persisted if store attached)."""
+        self._paused.add(surface_id)
+        if self._store is not None:
+            self._store.pause(surface_id)
+
+    def resume(self, surface_id: str) -> None:
+        """Resume a paused surface and reset its fail counter."""
+        self._paused.discard(surface_id)
+        self._counts[surface_id] = 0
+        if self._store is not None:
+            self._store.resume(surface_id)
+
+    # ------------------------------------------------------------------
+    # State query
+    # ------------------------------------------------------------------
+
+    def _store_paused(self, surface_id: str) -> bool:
+        """Read the persisted pause flag, fail-open. A store/DB fault (missing or corrupt
+        surface_state.db) must NEVER crash a send — treat it as not-paused."""
+        if self._store is None:
+            return False
+        try:
+            return bool(self._store.is_paused(surface_id))
+        except Exception as e:
+            logger.warning("circuit_store: read failed for %s (treating as not paused): %s",
+                           surface_id, e)
+            return False
+
+    def is_open(self, surface_id: str) -> bool:
+        """Return True if the surface should be skipped (open = bad = skip)."""
+        if surface_id in self._paused:
+            return True
+        if (self._counts.get(surface_id, 0)) >= self._threshold:
+            return True
+        if self._store_paused(surface_id):
+            return True
+        return False
+
+    def state(self, surface_id: str) -> dict:
+        """Return a snapshot of the surface's circuit state."""
+        count = self._counts.get(surface_id, 0)
+        manually_paused = surface_id in self._paused
+        store_paused = self._store_paused(surface_id)
+        auto_open = count >= self._threshold
+        return {
+            "surface_id": surface_id,
+            "consecutive_failures": count,
+            "threshold": self._threshold,
+            "auto_open": auto_open,
+            "manually_paused": manually_paused,
+            "store_paused": store_paused,
+            "is_open": manually_paused or auto_open or store_paused,
+        }

core/surfaces/continuity.py

@@ -0,0 +1,77 @@
+"""Idle-reset continuity bridge (Task 6, 2026-07-03).
+
+Seeds a short "last time we were discussing X" foundation message into a FRESH chat
+session, sourced from the prior chat episode's summary for the same ``thread_key`` —
+so continuity survives an idle/daily reset. The bridge is literally "recall my last
+episode for this chat key": a consumer of the episodic store (Tasks 1-2), not a
+second summary system.
+
+Deviation from the original brief (documented, not an oversight)
+------------------------------------------------------------------
+The brief additionally sketched a ``write_closing_episode`` helper called from
+``core/surfaces/dispatcher.py``'s ``if fresh:`` branch, writing a closing episode for
+the OUTGOING session at the reset boundary (with no summary available there — routing
+code isn't a summarizer). That write is deliberately NOT implemented:
+
+``SqliteMemoryProvider.record_episode`` upserts
+``ON CONFLICT(user_id, session_id) DO UPDATE SET summary=excluded.summary`` —
+keyed by ``(user_id, session_id)``, NOT ``thread_key``. Task 6 Part A (see
+``agents/task/session/cleanup.py``) already writes a REAL H-MEM-derived summary for
+that same ``session_id`` when the session is actually torn down. In the common case
+the old session has already been LRU/idle-evicted (cleanup already ran, already wrote
+a good summary) by the time a new inbound message triggers ``fresh`` for its
+thread_key — so a dispatcher-side null-summary write would land AFTER and CLOBBER the
+good one via that same upsert. Rather than add cross-site write-ordering/locking to
+make a second write site safe, this bridge is written from exactly ONE place
+(cleanup()), which is also the only place a real summary is available.
+
+Known limitation (v1, acceptable): a session that is still resident — not yet
+LRU/idle-evicted, so its cleanup() (and therefore its summary-bearing episode) hasn't
+run yet — will not bridge on the very next reset boundary for its thread_key; the
+bridge only starts working once that session's cleanup episode has landed. Task 5's
+broader "recent activity" digest still covers that window ("what did you do"), just
+not the more specific "what were we just discussing".
+"""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+async def build_bridge_message(*, user_id: Optional[str], thread_key: Optional[str]):
+    """Recall the most recent ``kind="chat"`` episode with a non-empty summary for
+    ``thread_key`` and wrap it as a ``SESSION_BRIDGE`` control message.
+
+    Returns None when: ``AutonomyConfig.continuity_bridge_enabled()`` is False,
+    ``thread_key`` is falsy, no prior chat episode exists for it, or every recalled
+    episode has an empty/whitespace-only summary. Fail-open — any error returns None.
+    """
+    try:
+        from agents.task.constants import AutonomyConfig
+        if not AutonomyConfig.continuity_bridge_enabled() or not thread_key:
+            return None
+
+        from modules.memory.registry import memory_recall_episodes
+        rows = await memory_recall_episodes(
+            user_id=user_id, thread_key=thread_key, kind="chat", limit=3, order="newest")
+
+        summary = None
+        for row in rows or []:
+            candidate = (getattr(row, "summary", None) or "").strip()
+            if candidate:
+                summary = candidate
+                break
+        if not summary:
+            return None
+
+        from modules.llm.messages import make_control_message, MessageOrigin
+        return make_control_message(
+            "Continuing an earlier conversation with this contact. "
+            f"Last time: {summary[:600]}",
+            MessageOrigin.SESSION_BRIDGE,
+        )
+    except Exception:
+        logger.warning("build_bridge_message failed", exc_info=True)
+        return None