byte-bot 0.1.0__py3-none-any.whl

byte_bot/adapters/legacy.py

@@ -0,0 +1,506 @@
+"""Static legacy configured-command observation bridge (B12/B13).
+
+Uses only the existing bounded executor in :mod:`byte_bot.projects`.
+Opaque command text stays opaque: it is exposed solely as bounded legacy
+content and never parsed into Sessions, lifecycle, checks, blockers,
+events or success. Batches explicitly carry health, completeness and
+capabilities, and :func:`batches_to_snapshot` projects them into the
+normalized :class:`Snapshot` source-health representation with zero typed
+entities. Exact local argv and per-project timeout overrides are
+preserved. External use of opaque text is deny-by-default. No dynamic
+imports and no transport code live in this module.
+
+Only the documented ``docs/structured-source.md`` protocol (implemented
+outside this module) may create typed normalized fields. This module
+never parses command output as that protocol, even when the text happens
+to look like JSON or contains lifecycle-like markers.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from byte_bot.config import Config, ProjectConfig
+from byte_bot.model import (
+    AdapterInfo,
+    CollectionError,
+    Machine,
+    Project,
+    Snapshot,
+    SourceHealth,
+    SourceStatus,
+)
+from byte_bot.projects import run_command
+
+ADAPTER_NAME = "legacy-command"
+ADAPTER_VERSION = "1"
+
+LEGACY_VIEWS: tuple[str, ...] = ("status", "agents")
+COMPAT_VIEWS: tuple[str, ...] = (
+    "status",
+    "agents",
+    "legacy-mobile-status",
+    "legacy-mobile-agents",
+    "journal",
+)
+
+DESTINATION_ID = "telegram:default"
+
+DEFAULT_LEGACY_INTERVAL_SECONDS = 30
+COMPAT_ENTRY_MAX_BYTES = 32 * 1024
+COMPAT_TOTAL_MAX_BYTES = 256 * 1024
+
+AVAILABLE = "available"
+UNAVAILABLE = "unavailable"
+UNSUPPORTED = "unsupported"
+ERROR = "error"
+
+#: Static snapshot capability projection for legacy-command sources. Only
+#: generic opaque-text and source-health capabilities are ever advertised
+#: as available; typed normalized capabilities stay unsupported because
+#: opaque output never yields typed entities.
+SNAPSHOT_CAPABILITIES: tuple[str, ...] = ("legacy-text", "source-health")
+
+
+def legacy_source_id(project_id: str) -> str:
+    """Return the stable source id for a schema-1 project."""
+    return f"legacy:{project_id.casefold()}"
+
+
+@dataclass(frozen=True)
+class Capability:
+    """Per-field availability with a human-readable reason."""
+
+    name: str
+    availability: str
+    reason: str
+    source_version: str | None = ADAPTER_VERSION
+
+    def __post_init__(self) -> None:
+        if self.availability not in (AVAILABLE, UNAVAILABLE, UNSUPPORTED, ERROR):
+            raise ValueError(f"unknown availability {self.availability!r}")
+
+
+@dataclass(frozen=True)
+class LegacySource:
+    """Exact local observation descriptor for one schema-1 project."""
+
+    source_id: str
+    project_id: str
+    status_argv: tuple[str, ...] = ()
+    agents_argv: tuple[str, ...] = ()
+    timeout_seconds: int = 6
+    interval_seconds: int = DEFAULT_LEGACY_INTERVAL_SECONDS
+    adapter_name: str = ADAPTER_NAME
+
+
+@dataclass(frozen=True)
+class LegacyDestination:
+    """Optional pre-migration destination identity. No transport behavior."""
+
+    destination_id: str = DESTINATION_ID
+
+
+@dataclass(frozen=True)
+class LegacyDisclosurePolicy:
+    """Deny-by-default external disclosure for opaque legacy content."""
+
+    allowed_sources: tuple[str, ...] = ()
+
+    def allows(self, source_id: str) -> bool:
+        return source_id in self.allowed_sources
+
+
+@dataclass(frozen=True)
+class RuntimeSettings:
+    """In-memory schema-1 normalization: sources, destination, disclosure."""
+
+    sources: tuple[LegacySource, ...] = ()
+    destination: LegacyDestination | None = None
+    disclosure: LegacyDisclosurePolicy = field(default_factory=LegacyDisclosurePolicy)
+
+
+@dataclass(frozen=True)
+class ObservationBatch:
+    """One legacy observation. Typed entity lists are always empty."""
+
+    source_id: str
+    project_id: str
+    adapter_name: str
+    adapter_version: str
+    view: str
+    observed_at: datetime
+    complete: bool
+    health: SourceHealth
+    error: CollectionError | None
+    capabilities: tuple[Capability, ...]
+    sessions: tuple[object, ...] = ()
+    checks: tuple[object, ...] = ()
+    blockers: tuple[object, ...] = ()
+    events: tuple[object, ...] = ()
+    legacy_text: str | None = None
+    legacy_truncated: bool = False
+    argv: tuple[str, ...] = ()
+    timeout_seconds: int = 6
+
+
+def build_legacy_source(project: ProjectConfig, default_timeout: int) -> LegacySource:
+    """Preserve exact local argv and the per-project timeout override."""
+    timeout = project.command_timeout_seconds or default_timeout
+    return LegacySource(
+        source_id=legacy_source_id(project.project_id),
+        project_id=project.project_id,
+        status_argv=tuple(project.status_command),
+        agents_argv=tuple(project.agents_command),
+        timeout_seconds=timeout,
+        interval_seconds=project.interval_seconds,
+    )
+
+
+def build_runtime_settings(config: Config) -> RuntimeSettings:
+    """Normalize schema-1 config into explicit source/destination/disclosure."""
+    sources = tuple(
+        build_legacy_source(project, config.command_timeout_seconds)
+        for project in config.projects
+    )
+    return RuntimeSettings(
+        sources=sources,
+        destination=LegacyDestination(),
+        disclosure=LegacyDisclosurePolicy(),
+    )
+
+
+def is_external_opaque_allowed(policy: LegacyDisclosurePolicy, source_id: str) -> bool:
+    """Deny-by-default gate for any opaque external disclosure."""
+    if not isinstance(policy, LegacyDisclosurePolicy):
+        return False
+    return policy.allows(source_id)
+
+
+def _default_capabilities(has_text: bool) -> tuple[Capability, ...]:
+    reason = "opaque legacy text never yields typed entities"
+    text_availability = AVAILABLE if has_text else UNAVAILABLE
+    text_reason = (
+        "bounded opaque legacy content" if has_text else "no successful observation"
+    )
+    return (
+        Capability("sessions", UNSUPPORTED, reason),
+        Capability("checks", UNSUPPORTED, reason),
+        Capability("blockers", UNSUPPORTED, reason),
+        Capability("structured-events", UNSUPPORTED, reason),
+        Capability("legacy-text", text_availability, text_reason),
+        Capability("source-health", AVAILABLE, "executor outcome recorded"),
+    )
+
+
+def _classify_failure(text: str) -> str:
+    lowered = text.lower()
+    if "timed out" in lowered:
+        return "timeout"
+    if "exceeded" in lowered and "kib" in lowered:
+        return "overflow"
+    if "not found" in lowered:
+        return "not_found"
+    if "no command configured" in lowered:
+        return "not_configured"
+    if "failed to start" in lowered:
+        return "start_failed"
+    if "invalid" in lowered:
+        return "invalid_command"
+    return "command_failed"
+
+
+def observe_legacy(
+    source: LegacySource,
+    view: str = "status",
+    *,
+    now: datetime | None = None,
+) -> ObservationBatch:
+    """Run the exact configured argv and wrap the outcome in a batch.
+
+    Only ``status``/``agents`` views execute local commands. No marker or
+    substring in the output ever becomes a Session, check, blocker, event
+    or success signal.
+    """
+    if view not in LEGACY_VIEWS:
+        raise ValueError(f"unknown legacy view {view!r}")
+    observed_at = now if now is not None else datetime.now(UTC)
+    argv = source.status_argv if view == "status" else source.agents_argv
+    if not argv:
+        health = SourceHealth(
+            source_id=source.source_id,
+            status=SourceStatus.ERROR,
+            detail="no command configured",
+            observed_at=observed_at,
+        )
+        return ObservationBatch(
+            source_id=source.source_id,
+            project_id=source.project_id,
+            adapter_name=ADAPTER_NAME,
+            adapter_version=ADAPTER_VERSION,
+            view=view,
+            observed_at=observed_at,
+            complete=False,
+            health=health,
+            error=CollectionError(
+                code="not_configured",
+                message="no command configured",
+                source_id=source.source_id,
+            ),
+            capabilities=_default_capabilities(False),
+            argv=(),
+            timeout_seconds=source.timeout_seconds,
+        )
+    result = run_command(argv, source.timeout_seconds)
+    if result.ok:
+        health = SourceHealth(
+            source_id=source.source_id,
+            status=SourceStatus.OK,
+            detail="ok",
+            observed_at=observed_at,
+        )
+        return ObservationBatch(
+            source_id=source.source_id,
+            project_id=source.project_id,
+            adapter_name=ADAPTER_NAME,
+            adapter_version=ADAPTER_VERSION,
+            view=view,
+            observed_at=observed_at,
+            complete=True,
+            health=health,
+            error=None,
+            capabilities=_default_capabilities(True),
+            legacy_text=result.text,
+            legacy_truncated=False,
+            argv=tuple(argv),
+            timeout_seconds=source.timeout_seconds,
+        )
+    code = _classify_failure(result.text)
+    truncated = code == "overflow"
+    health = SourceHealth(
+        source_id=source.source_id,
+        status=SourceStatus.ERROR,
+        detail=result.text[:800],
+        observed_at=observed_at,
+    )
+    return ObservationBatch(
+        source_id=source.source_id,
+        project_id=source.project_id,
+        adapter_name=ADAPTER_NAME,
+        adapter_version=ADAPTER_VERSION,
+        view=view,
+        observed_at=observed_at,
+        complete=False,
+        health=health,
+        error=CollectionError(
+            code=code,
+            message=result.text[:800],
+            source_id=source.source_id,
+        ),
+        capabilities=_default_capabilities(False),
+        legacy_text=None,
+        legacy_truncated=truncated,
+        argv=tuple(argv),
+        timeout_seconds=source.timeout_seconds,
+    )
+
+
+def batches_to_snapshot(
+    machine: Machine,
+    batches: tuple[ObservationBatch, ...] | list[ObservationBatch],
+    *,
+    generated_at: datetime | None = None,
+    projects: tuple[Project, ...] = (),
+) -> Snapshot:
+    """Project legacy batches into a normalized snapshot (B13).
+
+    Every source appears in ``source_health`` with its executor outcome;
+    failed batches additionally appear in ``errors``. Sessions, blockers,
+    checks and events are always empty: opaque ``legacy_text`` is never
+    parsed, so marker-rich output cannot fabricate typed entities and the
+    raw text never enters snapshot JSON. Adapter entries advertise only
+    the generic ``SNAPSHOT_CAPABILITIES``.
+    """
+    moment = generated_at if generated_at is not None else datetime.now(UTC)
+    adapters: dict[str, AdapterInfo] = {}
+    health: dict[str, SourceHealth] = {}
+    errors: list[CollectionError] = []
+    for batch in batches:
+        if batch.source_id not in adapters:
+            adapters[batch.source_id] = AdapterInfo(
+                name=batch.adapter_name,
+                instance_id=batch.source_id,
+                version=batch.adapter_version,
+                capabilities=SNAPSHOT_CAPABILITIES,
+                provider=None,
+            )
+        # Last batch per source wins for health; errors accumulate.
+        health[batch.source_id] = batch.health
+        if batch.error is not None:
+            errors.append(batch.error)
+    ordered_errors = sorted(
+        errors, key=lambda e: (e.code, e.source_id or "", e.message)
+    )
+    return Snapshot(
+        machine=machine,
+        generated_at=moment,
+        projects=tuple(projects),
+        adapters=tuple(sorted(adapters.values(), key=lambda a: a.instance_id)),
+        sessions=(),
+        blockers=(),
+        checks=(),
+        events=(),
+        source_health=tuple(sorted(health.values(), key=lambda h: h.source_id)),
+        errors=tuple(ordered_errors),
+        warnings=(),
+        omitted_sessions=0,
+        omitted_events=0,
+    )
+
+
+def _truncate_entry_text(text: str) -> str:
+    raw = text.encode("utf-8")[:COMPAT_ENTRY_MAX_BYTES]
+    return raw.decode("utf-8", errors="ignore")
+
+
+@dataclass
+class CompatibilityEntry:
+    """Bounded private opaque cache record. Never part of snapshot JSON."""
+
+    text: str
+    collected_at: float
+    expires_at: float
+    sensitivity: str = "opaque"
+
+
+class CompatibilityCache:
+    """Bounded newest-wins cache keyed by (source_id, view).
+
+    Limits: 32 KiB per entry, 256 KiB total with oldest-first eviction and
+    an explicit omission count. Entries expire after their TTL; expired or
+    missing entries report unavailable with no raw fallback.
+    """
+
+    def __init__(self) -> None:
+        self._entries: dict[tuple[str, str], CompatibilityEntry] = {}
+        self.omitted = 0
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def to_dict(self) -> dict[str, object]:
+        """Return a bounded JSON-safe persistence representation."""
+        entries = []
+        for (source_id, view), entry in sorted(self._entries.items()):
+            entries.append(
+                {
+                    "source_id": source_id,
+                    "view": view,
+                    "text": entry.text,
+                    "collected_at": entry.collected_at,
+                    "expires_at": entry.expires_at,
+                    "sensitivity": entry.sensitivity,
+                }
+            )
+        return {"schema": 1, "omitted": self.omitted, "entries": entries}
+
+    @classmethod
+    def from_dict(cls, raw: object) -> CompatibilityCache:
+        """Restore a cache without trusting persisted sizes or field types."""
+        if not isinstance(raw, dict) or raw.get("schema", 1) != 1:
+            raise ValueError("invalid compatibility cache")
+        entries = raw.get("entries", [])
+        omitted = raw.get("omitted", 0)
+        if not isinstance(entries, list):
+            raise ValueError("compatibility entries must be an array")
+        if isinstance(omitted, bool) or not isinstance(omitted, int) or omitted < 0:
+            raise ValueError("compatibility omitted must be a non-negative integer")
+
+        cache = cls()
+        cache.omitted = omitted
+        for item in entries:
+            if not isinstance(item, dict):
+                raise ValueError("compatibility entry must be an object")
+            source_id = item.get("source_id")
+            view = item.get("view")
+            text = item.get("text")
+            collected_at = item.get("collected_at")
+            expires_at = item.get("expires_at")
+            sensitivity = item.get("sensitivity", "opaque")
+            if (
+                not isinstance(source_id, str)
+                or not source_id
+                or view not in COMPAT_VIEWS
+                or not isinstance(text, str)
+                or not isinstance(collected_at, (int, float))
+                or isinstance(collected_at, bool)
+                or not isinstance(expires_at, (int, float))
+                or isinstance(expires_at, bool)
+                or sensitivity != "opaque"
+            ):
+                raise ValueError("invalid compatibility entry")
+            cache._entries[(source_id, view)] = CompatibilityEntry(
+                text=_truncate_entry_text(text),
+                collected_at=float(collected_at),
+                expires_at=float(expires_at),
+            )
+        while cache._total_bytes() > COMPAT_TOTAL_MAX_BYTES and cache._entries:
+            oldest = min(cache._entries, key=lambda key: cache._entries[key].collected_at)
+            del cache._entries[oldest]
+            cache.omitted += 1
+        return cache
+
+    def _total_bytes(self) -> int:
+        return sum(len(e.text.encode("utf-8")) for e in self._entries.values())
+
+    def update(
+        self,
+        batch: ObservationBatch,
+        *,
+        now: float | None = None,
+        ttl_seconds: float | None = None,
+    ) -> None:
+        moment = time.time() if now is None else float(now)
+        ttl = (
+            float(3 * DEFAULT_LEGACY_INTERVAL_SECONDS)
+            if ttl_seconds is None
+            else float(ttl_seconds)
+        )
+        key = (batch.source_id, batch.view)
+        if batch.legacy_text is None or not batch.complete:
+            return
+        if key[1] not in COMPAT_VIEWS:
+            return
+        text = _truncate_entry_text(batch.legacy_text)
+        self._entries[key] = CompatibilityEntry(
+            text=text, collected_at=moment, expires_at=moment + ttl
+        )
+        while self._total_bytes() > COMPAT_TOTAL_MAX_BYTES and self._entries:
+            oldest = min(self._entries, key=lambda k: self._entries[k].collected_at)
+            del self._entries[oldest]
+            self.omitted += 1
+
+    def get_local(
+        self, source_id: str, view: str, *, now: float | None = None
+    ) -> str | None:
+        """Local legacy text view; None when missing or expired."""
+        moment = time.time() if now is None else float(now)
+        entry = self._entries.get((source_id, view))
+        if entry is None or moment > entry.expires_at:
+            return None
+        return entry.text
+
+    def get_external(
+        self,
+        source_id: str,
+        view: str,
+        policy: LegacyDisclosurePolicy,
+        *,
+        now: float | None = None,
+    ) -> str | None:
+        """External opaque disclosure. Deny-by-default: None unless allowed."""
+        if not is_external_opaque_allowed(policy, source_id):
+            return None
+        return self.get_local(source_id, view, now=now)