polyrob 0.5.0__py3-none-any.whl

agents/task/session_registry.py

@@ -0,0 +1,91 @@
+"""Session registry — maps session_id -> SessionOrchestrator.
+
+This is the single seam through which the active in-memory orchestrators are
+looked up and mutated. Today it wraps a plain in-process dict, which is what
+forces ``UVICORN_WORKERS=1`` in production (an orchestrator created in one
+worker is invisible to another). Keeping every access behind this interface
+means the future swap to a cross-process, SQLite-backed registry (WAL mode,
+jittered retry — see ``docs/ROB_CORE_SERVER_SPLIT_SPEC.md`` Phase E) is
+mechanical rather than a scavenger hunt through ``task_agent_lite``.
+
+The interface is intentionally small and dict-flavoured so callers read
+naturally:
+
+    registry.register(session_id, orchestrator)
+    orch = registry.get(session_id)
+    orch = registry.remove(session_id)      # pop, returns None if absent
+    if session_id in registry: ...
+    for sid, orch in registry.items(): ...
+    len(registry)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+
+class SessionRegistry:
+    """In-process registry of active session orchestrators.
+
+    Not thread/process shared. See module docstring for the scaling caveat.
+    """
+
+    def __init__(self) -> None:
+        self._orchestrators: Dict[str, Any] = {}
+
+    def register(self, session_id: str, orchestrator: Any, *, params: Optional[Dict[str, Any]] = None) -> None:
+        """Store (or replace) the orchestrator for ``session_id``.
+
+        ``params`` is accepted (and ignored) for signature parity with the
+        SQLite-backed registry, so callers can pass it without crashing whichever
+        backend ``SESSION_REGISTRY_BACKEND`` selected.
+        """
+        self._orchestrators[session_id] = orchestrator
+
+    def get(self, session_id: str) -> Optional[Any]:
+        """Return the orchestrator for ``session_id`` or ``None``."""
+        return self._orchestrators.get(session_id)
+
+    def route(self, session_id: str):
+        """Routing decision (P6). In-process registry knows only local sessions, so
+        the result is either LOCAL (handle here) or MISSING."""
+        from agents.task.session_route import SessionRoute, LOCAL, MISSING
+        orch = self._orchestrators.get(session_id)
+        if orch is not None:
+            return SessionRoute(status=LOCAL, orchestrator=orch)
+        return SessionRoute(status=MISSING)
+
+    def remove(self, session_id: str) -> Optional[Any]:
+        """Remove and return the orchestrator for ``session_id`` (``None`` if absent)."""
+        return self._orchestrators.pop(session_id, None)
+
+    def contains(self, session_id: str) -> bool:
+        return session_id in self._orchestrators
+
+    def count(self) -> int:
+        return len(self._orchestrators)
+
+    def items(self) -> List[Tuple[str, Any]]:
+        """Snapshot of (session_id, orchestrator) pairs — safe to mutate while iterating."""
+        return list(self._orchestrators.items())
+
+    def values(self) -> List[Any]:
+        """Snapshot of the registered orchestrators."""
+        return list(self._orchestrators.values())
+
+    def session_ids(self) -> List[str]:
+        return list(self._orchestrators.keys())
+
+    def clear(self) -> None:
+        self._orchestrators.clear()
+
+    # --- dict-flavoured conveniences ---
+
+    def __contains__(self, session_id: str) -> bool:
+        return session_id in self._orchestrators
+
+    def __len__(self) -> int:
+        return len(self._orchestrators)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(list(self._orchestrators.keys()))

agents/task/session_route.py

@@ -0,0 +1,35 @@
+"""Cross-worker session routing result (roadmap P6).
+
+The routing *decision* a worker makes for an incoming session request: handle it
+locally, report which worker owns it (so the caller can forward / return a
+meaningful 409 instead of a false 404), or report it missing. Built on the
+SQLite registry's cross-process visibility (``exists``/``owner_pid``); actual
+request forwarding (HTTP/IPC proxy) is a thin layer on top of this decision.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+LOCAL = "local"      # owned by this worker; orchestrator is in-process
+REMOTE = "remote"    # exists but owned by another worker (owner_pid set)
+MISSING = "missing"  # no such active session anywhere
+
+
+@dataclass(frozen=True)
+class SessionRoute:
+    status: str                       # LOCAL | REMOTE | MISSING
+    orchestrator: Optional[Any] = None  # set only when LOCAL
+    owner_pid: Optional[int] = None     # set for LOCAL and REMOTE
+
+    @property
+    def is_local(self) -> bool:
+        return self.status == LOCAL
+
+    @property
+    def is_remote(self) -> bool:
+        return self.status == REMOTE
+
+    @property
+    def is_missing(self) -> bool:
+        return self.status == MISSING

agents/task/sqlite_session_registry.py

@@ -0,0 +1,261 @@
+"""SQLite-backed session registry (roadmap P6 / §33 — the scale unlock).
+
+The in-process :class:`SessionRegistry` forces ``UVICORN_WORKERS=1``: an
+orchestrator created in one worker is invisible to another, so a request that
+lands on the wrong worker 404s. This variant keeps the **local object dict**
+(the live orchestrator can't cross processes) but ALSO mirrors session metadata to
+a shared SQLite ``active_sessions`` table (WAL + jittered retry) so every worker
+can see which sessions exist and who owns them — the routing foundation for
+``workers>1``.
+
+Drop-in compatible with ``SessionRegistry`` (register/get/remove/contains/count/…)
+plus cross-process methods: ``exists``, ``owner_pid``, ``global_session_ids``,
+``global_count``, ``heartbeat``, ``reap_stale``.
+
+Scope note: this gives cross-worker *visibility*, not transparent cross-worker
+*method calls* on a remote orchestrator (that needs sticky routing / IPC — a
+follow-up). With it, a worker can return a meaningful "owned by pid N / elsewhere"
+result instead of a false 404.
+"""
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from datetime import datetime, timedelta
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+from core.sqlite_util import execute_retry
+
+
+class SqliteSessionRegistry:
+    def __init__(self, db_path: str, *, worker_pid: Optional[int] = None) -> None:
+        self.db_path = db_path
+        self._pid = worker_pid or os.getpid()
+        # Per-process boot id: ownership is keyed on this, NOT the (reusable) pid.
+        # Two processes that happen to share a pid (PID reuse after a worker dies)
+        # still get distinct boot ids, so routing never mistakes one for the other.
+        self._boot_id = uuid.uuid4().hex
+        parent = os.path.dirname(db_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        self._orchestrators: Dict[str, Any] = {}
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        # owner_boot_id is in the CREATE so a FRESH DB never needs the ALTER — this
+        # avoids the concurrent-boot race where two workers both PRAGMA-see the column
+        # missing and both ALTER (the second crashing with "duplicate column name").
+        execute_retry(
+            self.db_path,
+            """
+            CREATE TABLE IF NOT EXISTS active_sessions (
+                session_id TEXT PRIMARY KEY,
+                worker_pid INTEGER NOT NULL,
+                status TEXT NOT NULL DEFAULT 'active',
+                params TEXT NOT NULL DEFAULT '{}',
+                last_seen_at TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                owner_boot_id TEXT
+            )
+            """,
+        )
+        # Migration for pre-existing DBs created before owner_boot_id. (No
+        # ALTER ... IF NOT EXISTS in SQLite.) Tolerate the "duplicate column name"
+        # error so a concurrent boot that adds it first can't crash this worker.
+        cols = execute_retry(
+            self.db_path, "PRAGMA table_info(active_sessions)", fetch="all",
+        ) or []
+        names = {row["name"] for row in cols}
+        if "owner_boot_id" not in names:
+            try:
+                execute_retry(
+                    self.db_path,
+                    "ALTER TABLE active_sessions ADD COLUMN owner_boot_id TEXT",
+                )
+            except Exception as e:  # concurrent add won the race — that's fine
+                if "duplicate column" not in str(e).lower():
+                    raise
+
+    # --- local object dict (compatible with SessionRegistry) -----------------
+
+    def register(self, session_id: str, orchestrator: Any, *, params: Optional[Dict[str, Any]] = None) -> None:
+        # Write the DB row BEFORE the local dict. route() reads the DB; if the DB
+        # write raised after we'd already stored the object locally, route() would
+        # return MISSING for a session this worker actually holds — a false 404, the
+        # exact failure this class exists to prevent.
+        now = datetime.now().isoformat()
+        execute_retry(
+            self.db_path,
+            """
+            INSERT INTO active_sessions
+                (session_id, worker_pid, owner_boot_id, status, params, last_seen_at, created_at)
+            VALUES (?,?,?,?,?,?,?)
+            ON CONFLICT(session_id) DO UPDATE SET
+                worker_pid=excluded.worker_pid, owner_boot_id=excluded.owner_boot_id,
+                status='active', params=excluded.params, last_seen_at=excluded.last_seen_at
+            """,
+            (session_id, self._pid, self._boot_id, "active", json.dumps(params or {}), now, now),
+        )
+        self._orchestrators[session_id] = orchestrator
+
+    def get(self, session_id: str) -> Optional[Any]:
+        """Return the LOCAL orchestrator object (None if owned by another worker)."""
+        return self._orchestrators.get(session_id)
+
+    def remove(self, session_id: str) -> Optional[Any]:
+        execute_retry(self.db_path, "DELETE FROM active_sessions WHERE session_id=?", (session_id,))
+        return self._orchestrators.pop(session_id, None)
+
+    def contains(self, session_id: str) -> bool:
+        return session_id in self._orchestrators
+
+    def count(self) -> int:
+        return len(self._orchestrators)
+
+    def items(self) -> List[Tuple[str, Any]]:
+        return list(self._orchestrators.items())
+
+    def values(self) -> List[Any]:
+        return list(self._orchestrators.values())
+
+    def session_ids(self) -> List[str]:
+        return list(self._orchestrators.keys())
+
+    def clear(self) -> None:
+        for sid in list(self._orchestrators):
+            execute_retry(self.db_path, "DELETE FROM active_sessions WHERE session_id=?", (sid,))
+        self._orchestrators.clear()
+
+    # --- cross-process metadata (SQLite) -------------------------------------
+
+    def exists(self, session_id: str) -> bool:
+        row = execute_retry(
+            self.db_path, "SELECT 1 FROM active_sessions WHERE session_id=?", (session_id,), fetch="one",
+        )
+        return row is not None
+
+    def route(self, session_id: str):
+        """Routing decision (P6): LOCAL (object is in this worker), REMOTE (exists but
+        owned by another worker — caller can forward / 409 with owner_pid), or MISSING."""
+        from agents.task.session_route import SessionRoute, LOCAL, REMOTE, MISSING
+        row = execute_retry(
+            self.db_path,
+            "SELECT worker_pid, owner_boot_id FROM active_sessions WHERE session_id=?",
+            (session_id,), fetch="one",
+        )
+        if row is None:
+            return SessionRoute(status=MISSING)
+        owner = int(row["worker_pid"])
+        owner_boot = row["owner_boot_id"]
+        # LOCAL only when the OWNING boot id is ours (pid match alone is not enough:
+        # a reused pid in a fresh process must not be treated as the same owner).
+        local = self._orchestrators.get(session_id)
+        if owner_boot == self._boot_id and local is not None:
+            return SessionRoute(status=LOCAL, orchestrator=local, owner_pid=owner)
+        return SessionRoute(status=REMOTE, owner_pid=owner)
+
+    def owner_pid(self, session_id: str) -> Optional[int]:
+        row = execute_retry(
+            self.db_path, "SELECT worker_pid FROM active_sessions WHERE session_id=?", (session_id,), fetch="one",
+        )
+        return int(row["worker_pid"]) if row else None
+
+    def owner_boot_id(self, session_id: str) -> Optional[str]:
+        row = execute_retry(
+            self.db_path, "SELECT owner_boot_id FROM active_sessions WHERE session_id=?", (session_id,), fetch="one",
+        )
+        return row["owner_boot_id"] if row else None
+
+    def global_session_ids(self) -> List[str]:
+        rows = execute_retry(self.db_path, "SELECT session_id FROM active_sessions", fetch="all")
+        return [r["session_id"] for r in rows]
+
+    def global_count(self) -> int:
+        row = execute_retry(self.db_path, "SELECT COUNT(*) AS c FROM active_sessions", fetch="one")
+        return int(row["c"]) if row else 0
+
+    def heartbeat(self, session_id: str) -> None:
+        execute_retry(
+            self.db_path, "UPDATE active_sessions SET last_seen_at=? WHERE session_id=?",
+            (datetime.now().isoformat(), session_id),
+        )
+
+    @staticmethod
+    def _pid_alive(pid: Optional[int]) -> bool:
+        """True if ``pid`` is a live process on THIS host.
+
+        Same-host multi-worker (uvicorn workers) is the supported ``workers>1``
+        deployment, so a signal-0 liveness probe is meaningful. Be conservative:
+        an unknown/None pid or any unexpected error is treated as ALIVE so we never
+        reap a possibly-live owner. (A cross-host DB would need a heartbeat-based
+        liveness signal; that deployment is out of scope for the live orchestrator.)
+        """
+        if not pid or pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+            return True
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True  # exists but owned by another user
+        except Exception:
+            return True
+
+    def reap_stale(self, ttl_seconds: int = 300) -> List[str]:
+        """Remove sessions whose last_seen_at is older than ttl. Returns reaped ids.
+
+        A row is reaped ONLY if it is truly abandoned: stale AND not held locally AND
+        its owning worker process is DEAD. A session sitting IDLE between user turns
+        does not step, so its heartbeat freezes — but it is still alive in its owning
+        worker and must never be reaped (deleting the row would force a false-404 and
+        leak that worker's orchestrator). Rows we hold locally, and rows whose
+        ``worker_pid`` is still alive on this host, are skipped; only genuinely
+        dead-worker rows are cleaned up. Complements the per-step heartbeat.
+        """
+        cutoff = (datetime.now() - timedelta(seconds=ttl_seconds)).isoformat()
+        # Sessions alive in THIS process, regardless of heartbeat staleness.
+        local_sids = set(self._orchestrators.keys())
+        rows = execute_retry(
+            self.db_path,
+            "SELECT session_id, worker_pid FROM active_sessions WHERE last_seen_at < ?",
+            (cutoff,), fetch="all",
+        )
+        # Reap only rows that are (a) not ours and (b) owned by a DEAD process. A
+        # stale row whose owner worker is still alive is an idle session on another
+        # worker — deleting it would false-404 and orphan that worker's orchestrator.
+        reaped = [
+            r["session_id"] for r in rows
+            if r["session_id"] not in local_sids and not self._pid_alive(r["worker_pid"])
+        ]
+        for sid in reaped:
+            # Re-check under the cutoff: don't delete a row that heartbeated between
+            # the SELECT and the DELETE (and re-skip if it somehow became local).
+            if sid in self._orchestrators:
+                continue
+            execute_retry(
+                self.db_path,
+                "DELETE FROM active_sessions WHERE session_id=? AND last_seen_at < ?",
+                (sid, cutoff),
+            )
+            self._orchestrators.pop(sid, None)
+        return reaped
+
+    # test helper: force a row's last_seen_at (e.g. into the past) for reap tests.
+    def _set_last_seen(self, session_id: str, iso: str) -> None:
+        execute_retry(self.db_path, "UPDATE active_sessions SET last_seen_at=? WHERE session_id=?", (iso, session_id))
+
+    # backwards-compatible alias
+    _set_last_seen_for_test = _set_last_seen
+
+    # --- dict-flavoured conveniences -----------------------------------------
+
+    def __contains__(self, session_id: str) -> bool:
+        return session_id in self._orchestrators
+
+    def __len__(self) -> int:
+        return len(self._orchestrators)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(list(self._orchestrators.keys()))

agents/task/surface_config.py

@@ -0,0 +1,185 @@
+"""Feature flags for the Singular Chat Interface (Surface contract).
+
+Read through this class (NOT BotConfig.get, which is getattr-backed and returns
+the default for any unknown key -> a gate read that way is permanently off).
+Reuses constants._bool_env so default-ON and default-OFF flags share one parser.
+"""
+import os
+from typing import Optional
+
+from agents.task.constants import _bool_env, local_mode_enabled
+
+
+def _int_env(name: str, default: int) -> int:
+    try:
+        v = os.getenv(name)
+        return int(v) if v is not None and v.strip() != "" else default
+    except (TypeError, ValueError):
+        return default
+
+
+class SurfaceConfig:
+    @staticmethod
+    def singular_chat_enabled() -> bool:
+        return _bool_env("SINGULAR_CHAT_ENABLED", False)
+
+    @staticmethod
+    def telegram_surface_enabled() -> bool:
+        return _bool_env("TELEGRAM_SURFACE_ENABLED", False)
+
+    @staticmethod
+    def whatsapp_surface_enabled() -> bool:
+        return _bool_env("WHATSAPP_SURFACE_ENABLED", False)
+
+    @staticmethod
+    def email_surface_enabled() -> bool:
+        """Run the email surface (IMAP poll inbound + SMTP outbound). Default OFF.
+        v1 is correspondent-only — owner-by-email stays OFF until verified-sender lands."""
+        return _bool_env("EMAIL_SURFACE_ENABLED", False)
+
+    @staticmethod
+    def email_imap_poll_sec() -> int:
+        """Seconds between IMAP polls for new mail (no IDLE in v1)."""
+        return _int_env("EMAIL_IMAP_POLL_SEC", 60)
+
+    @staticmethod
+    def chat_intent_classifier_enabled() -> bool:
+        return _bool_env("CHAT_INTENT_CLASSIFIER", False)
+
+    # --- WS-A three-tier access model (owner/correspondent/denied) -----------
+    @staticmethod
+    def correspondent_access_enabled() -> bool:
+        """Resolve every inbound to an access tier (OWNER/CORRESPONDENT/DENIED) at the
+        routing boundary. Default OFF — when off, route_inbound is byte-identical to
+        today (only the legacy pairing gate applies). When on, a non-owner is routable
+        only as a known correspondent (its reply is DATA delivered to the originating
+        session, never a steering turn)."""
+        return _bool_env("CORRESPONDENT_ACCESS_ENABLED", False)
+
+    @staticmethod
+    def correspondent_require_approval() -> bool:
+        """A newly auto-seeded correspondent is PENDING (owner must approve) before its
+        replies are routable. Default ON — a third party the agent contacted does not
+        become a trusted-data channel until the owner ratifies it. Set
+        CORRESPONDENT_REQUIRE_APPROVAL=false for single-user/local convenience."""
+        return _bool_env("CORRESPONDENT_REQUIRE_APPROVAL", True)
+
+    @staticmethod
+    def correspondent_max_new_per_day() -> int:
+        """Per-tenant cap on NEW correspondents seeded per 24h — bounds the blast radius
+        of an injection that tricks the agent into mass-contacting addresses."""
+        return _int_env("CORRESPONDENT_MAX_NEW_PER_DAY", 20)
+
+    # --- #9 voice transcription ---------------------------------------------
+    @staticmethod
+    def voice_transcription_enabled() -> bool:
+        """Transcribe inbound voice/audio messages to text before routing (#9).
+        Default ON: when the faster-whisper extra is installed, voice notes are
+        transcribed; when it isn't, the surface degrades gracefully (the inbound guard
+        tells the user voice is unavailable instead of routing an empty turn).
+        Set VOICE_TRANSCRIPTION_ENABLED=false to turn it off."""
+        return _bool_env("VOICE_TRANSCRIPTION_ENABLED", True)
+
+    @staticmethod
+    def voice_transcription_model() -> str:
+        """faster-whisper model size: tiny|base|small|medium|large-v3. `base` balances
+        CPU latency vs accuracy for short voice notes."""
+        return (os.getenv("VOICE_TRANSCRIPTION_MODEL") or "base").strip()
+
+    @staticmethod
+    def voice_transcription_required() -> bool:
+        """When ON, a missing faster-whisper engine is a startup ERROR (not just WARN).
+        Default OFF: most deploys degrade gracefully (voice refused with a notice)."""
+        return _bool_env("VOICE_TRANSCRIPTION_REQUIRED", False)
+
+    @staticmethod
+    def voice_transcript_echo_enabled() -> bool:
+        """Echo the transcript back into the chat as a persistent, voice-note-anchored
+        message before the agent answers (Telegram + WhatsApp). Default ON; purely additive.
+        Set VOICE_TRANSCRIPT_ECHO=false for byte-identical prior behavior."""
+        return _bool_env("VOICE_TRANSCRIPT_ECHO", True)
+
+    # --- #8 Telegram incremental streaming ----------------------------------
+    @staticmethod
+    def telegram_incremental_stream() -> bool:
+        """Live `editMessageText` streaming on Telegram (#8). Default OFF — the buffered
+        one-send-on-finalize path stays the safe default; opt in per deployment."""
+        return _bool_env("TELEGRAM_INCREMENTAL_STREAM", False)
+
+    @staticmethod
+    def telegram_stream_edit_interval_sec() -> float:
+        """Minimum seconds between live stream edits (flood-control). Telegram tolerates
+        only a few edits/sec; 1.5s is conservative. `0` edits on every delta (tests)."""
+        try:
+            v = os.getenv("TELEGRAM_STREAM_EDIT_INTERVAL_SEC")
+            return float(v) if v is not None and v.strip() != "" else 1.5
+        except (TypeError, ValueError):
+            return 1.5
+
+    # --- P0.1 session-boundary policy ---------------------------------------
+    @staticmethod
+    def session_reset_mode() -> str:
+        """idle | daily | both | none. Default `idle` everywhere (#7): a fresh thread
+        after a cooldown is natural and memory recall bridges the gap. The server flip
+        (none->idle) is gated on the recreate-race (#2) + mute-on-resume (#0) fixes,
+        both landed, so a reset can't drop a reply or double-build an orchestrator.
+        Pin `SESSION_RESET_MODE=none` to restore the legacy inert behavior; `daily` is
+        opt-in (server-local-tz skew). The idle WINDOW still differs by profile
+        (`session_idle_minutes`: 720 local / 1440 server)."""
+        return (os.getenv("SESSION_RESET_MODE") or "idle").strip().lower()
+
+    @staticmethod
+    def session_idle_minutes() -> int:
+        """Idle threshold; a chat older than this since last activity starts fresh.
+        Default 1440 (24h); 720 (12h) under POLYROB_LOCAL (a personal bot rolls sooner)."""
+        return _int_env("SESSION_IDLE_MINUTES", 720 if local_mode_enabled() else 1440)
+
+    @staticmethod
+    def session_reset_hour() -> int:
+        """Local hour (0-23) for the daily session roll."""
+        return _int_env("SESSION_RESET_HOUR", 4)
+
+    # --- outbound durability -------------------------------------------------
+    @staticmethod
+    def outbound_queue_enabled() -> bool:
+        """Route final outbound messages through the durable OutboundDeliveryQueue
+        (retry + dead-letter). Default OFF -> publish() sends directly (legacy). Streaming
+        deltas are always best-effort (never queued)."""
+        return _bool_env("OUTBOUND_QUEUE_ENABLED", False)
+
+    # --- a5 surface GC -------------------------------------------------------
+    @staticmethod
+    def surface_gc_enabled() -> bool:
+        """Periodic GC of stale chat<->session bindings (a5). Default ON under the local
+        profile when the chat bus is on; OFF on the multi-tenant server until validated."""
+        return _bool_env(
+            "SURFACE_GC_ENABLED",
+            local_mode_enabled() and SurfaceConfig.singular_chat_enabled(),
+        )
+
+    @staticmethod
+    def surface_gc_horizon_secs() -> int:
+        """Bindings with no activity for longer than this are purged. ``max(2x idle
+        window, 7d)`` so GC never races the idle-reset boundary — a pointer is only
+        dropped well after it would already start a fresh thread."""
+        return max(SurfaceConfig.session_idle_minutes() * 60 * 2, 7 * 86400)
+
+    # --- webhook signing secrets ------------------------------------------------
+    @staticmethod
+    def whatsapp_template_name() -> str:
+        """Approved utility template used to re-open the 24h window for a proactive msg."""
+        return (os.getenv("WHATSAPP_TEMPLATE_NAME") or "task_ready").strip()
+
+    @staticmethod
+    def webhook_secret(surface_id: str) -> "Optional[str]":
+        """Read {SURFACE}_WEBHOOK_SECRET from env. Surface id is upper-cased:
+        whatsapp -> WHATSAPP_WEBHOOK_SECRET. Returns stripped value or None."""
+        v = os.getenv(f"{surface_id.upper()}_WEBHOOK_SECRET")
+        return v.strip() if v and v.strip() else None
+
+    @staticmethod
+    def webhook_verify_token(surface_id: str) -> "Optional[str]":
+        """Read {SURFACE}_VERIFY_TOKEN from env. Surface id is upper-cased:
+        whatsapp -> WHATSAPP_VERIFY_TOKEN. Returns stripped value or None."""
+        v = os.getenv(f"{surface_id.upper()}_VERIFY_TOKEN")
+        return v.strip() if v and v.strip() else None

agents/task/telemetry/__init__.py

@@ -0,0 +1,58 @@
+"""
+Telemetry package for task.
+
+This package provides functionality for capturing telemetry events
+and metrics from the task system.
+"""
+
+import logging
+
+# Setup logging
+from agents.task.logging_config import get_task_logger
+logger = get_task_logger('telemetry')
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s %(levelname)-8s [%(name)s] %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# Import primary classes - safe imports that don't create circular dependencies
+from agents.task.telemetry.views import (
+    BaseTelemetryEvent,
+    AgentRunTelemetryEvent,
+    AgentStepTelemetryEvent,
+    AgentEndTelemetryEvent,
+    LLMRequestTelemetryEvent,
+    SessionRelationshipTelemetryEvent,
+    InterfaceTelemetryEvent,
+    SessionStartTelemetryEvent,
+    SessionCompletionTelemetryEvent,
+    ProviderFailureEvent,
+    ProviderFallbackSuccessEvent
+)
+
+# Lazy import ProductTelemetry to avoid circular references
+# This way consumers can import the module without triggering additional imports
+ProductTelemetry = None
+
+def get_telemetry():
+    """Get the ProductTelemetry instance safely using singleton pattern"""
+    from agents.task.path import get_safe_singleton
+    from agents.task.telemetry.service import ProductTelemetry
+    return get_safe_singleton(ProductTelemetry)()
+
+__all__ = [
+    "get_telemetry",  # New function for safe access
+    "BaseTelemetryEvent",
+    "AgentRunTelemetryEvent",
+    "AgentStepTelemetryEvent",
+    "AgentEndTelemetryEvent",
+    "LLMRequestTelemetryEvent",
+    "SessionRelationshipTelemetryEvent",
+    "InterfaceTelemetryEvent",
+    "SessionStartTelemetryEvent",
+    "SessionCompletionTelemetryEvent",
+    "ProviderFailureEvent",
+    "ProviderFallbackSuccessEvent"
+]