skcomms 0.1.3__py3-none-any.whl

skcomms/__init__.py

@@ -0,0 +1,58 @@
+"""skcomms — sovereign communications for AI agents.
+
+Multi-channel transport (Syncthing/file/websocket/WebRTC/Nostr/Tailscale/...)
+unified under FQID ``<agent>@<operator>.<realm>`` sovereign addressing.
+
+Transport layer (from skcomms, now canonical here):
+    from skcomms import SKComms
+    from skcomms.core import SKComms
+    from skcomms.models import MessageEnvelope
+
+FQID / realm layer (pre-alpha stubs, implementations landing in coord tasks):
+    from skcomms.envelope import ...
+    from skcomms.realm import ...
+    from skcomms.identity import ...
+    from skcomms.cluster import ...
+"""
+
+__version__ = "0.1.3"
+
+from .core import SKComms, SKComm
+from .crypto import EnvelopeCrypto, KeyStore
+from .models import (
+    MessageEnvelope,
+    MessageMetadata,
+    MessagePayload,
+    MessageType,
+    RoutingConfig,
+    RoutingMode,
+)
+from .envelope import Envelope, SignedEnvelope
+from .signing import EnvelopeSigner, EnvelopeVerifier, VerificationResult
+from .transport import HealthStatus, SendResult, Transport, TransportError, TransportStatus
+
+__all__ = [
+    # Transport layer
+    "SKComms",
+    "SKComm",  # deprecated alias
+    "MessageEnvelope",
+    "MessageMetadata",
+    "MessagePayload",
+    "MessageType",
+    "RoutingConfig",
+    "RoutingMode",
+    "Transport",
+    "TransportError",
+    "TransportStatus",
+    "HealthStatus",
+    "SendResult",
+    "EnvelopeCrypto",
+    "KeyStore",
+    "Envelope",
+    "SignedEnvelope",
+    "EnvelopeSigner",
+    "EnvelopeVerifier",
+    "VerificationResult",
+    # FQID / realm layer (stubs — implementations pending)
+    # envelope, realm, identity, cluster importable directly
+]

skcomms/ack.py

@@ -0,0 +1,296 @@
+"""
+SKComms delivery acknowledgment tracker.
+
+When a message is sent with ack_requested=True, the sender
+records it as "pending ACK." When the receiver processes the
+message, it automatically sends an ACK envelope back. When
+the original sender receives the ACK, the pending entry is
+resolved as "confirmed."
+
+Pending ACKs that exceed the timeout are marked "timed_out"
+and can be retried or escalated.
+
+Persistence: pending ACKs are stored as JSON in ~/.skcomms/acks/
+so they survive process restarts.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .config import SKCOMMS_HOME
+from .models import MessageEnvelope
+
+logger = logging.getLogger("skcomms.ack")
+
+ACKS_DIR_NAME = "acks"
+ACK_SUFFIX = ".ack.json"
+DEFAULT_ACK_TIMEOUT = 300
+
+
+class AckStatus(str, Enum):
+    """State of a pending acknowledgment."""
+
+    PENDING = "pending"
+    CONFIRMED = "confirmed"
+    TIMED_OUT = "timed_out"
+
+
+class PendingAck(BaseModel):
+    """A tracked outbound message awaiting acknowledgment.
+
+    Attributes:
+        envelope_id: ID of the sent message.
+        recipient: Who the message was sent to.
+        sent_at: When the message was sent.
+        ack_timeout: Seconds to wait for an ACK.
+        status: Current ACK state.
+        confirmed_at: When the ACK was received.
+        confirmed_via: Transport that delivered the ACK.
+    """
+
+    envelope_id: str
+    recipient: str
+    sent_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    ack_timeout: int = DEFAULT_ACK_TIMEOUT
+    status: AckStatus = AckStatus.PENDING
+    confirmed_at: Optional[datetime] = None
+    confirmed_via: Optional[str] = None
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if this ACK has timed out."""
+        if self.status != AckStatus.PENDING:
+            return False
+        age = (datetime.now(timezone.utc) - self.sent_at).total_seconds()
+        return age > self.ack_timeout
+
+
+class AckTracker:
+    """Tracks outbound messages awaiting delivery acknowledgment.
+
+    Persists pending ACKs as JSON files. Resolves them when
+    matching ACK envelopes are received. Detects timeouts.
+
+    Args:
+        acks_dir: Directory for ACK tracking files.
+        default_timeout: Default seconds to wait for ACK.
+    """
+
+    def __init__(
+        self,
+        acks_dir: Optional[Path] = None,
+        default_timeout: int = DEFAULT_ACK_TIMEOUT,
+    ):
+        self._dir = acks_dir or Path(SKCOMMS_HOME).expanduser() / ACKS_DIR_NAME
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._default_timeout = default_timeout
+
+    @property
+    def acks_dir(self) -> Path:
+        """Path to the ACK tracking directory."""
+        return self._dir
+
+    def track(self, envelope: MessageEnvelope) -> Optional[PendingAck]:
+        """Begin tracking an outbound message for ACK.
+
+        Only tracks if ack_requested is True on the envelope.
+
+        Args:
+            envelope: The sent message envelope.
+
+        Returns:
+            PendingAck if tracking started, None if ACK not requested.
+        """
+        if not envelope.routing.ack_requested:
+            return None
+        if envelope.is_ack:
+            return None
+
+        pending = PendingAck(
+            envelope_id=envelope.envelope_id,
+            recipient=envelope.recipient,
+            ack_timeout=self._default_timeout,
+        )
+
+        path = self._dir / f"{envelope.envelope_id}{ACK_SUFFIX}"
+        path.write_text(pending.model_dump_json(indent=2))
+        logger.debug("Tracking ACK for %s -> %s", envelope.envelope_id[:8], envelope.recipient)
+        return pending
+
+    def process_ack(self, ack_envelope: MessageEnvelope) -> Optional[PendingAck]:
+        """Process a received ACK envelope and resolve the pending entry.
+
+        The ACK's content holds the original envelope_id.
+
+        Args:
+            ack_envelope: A received ACK-type envelope.
+
+        Returns:
+            The resolved PendingAck, or None if no matching pending found.
+        """
+        if not ack_envelope.is_ack:
+            return None
+
+        original_id = ack_envelope.payload.content
+        path = self._dir / f"{original_id}{ACK_SUFFIX}"
+
+        if not path.exists():
+            logger.debug("ACK for unknown envelope %s — ignoring", original_id[:8])
+            return None
+
+        try:
+            pending = PendingAck.model_validate_json(path.read_text())
+        except Exception as exc:
+            logger.warning("Failed to read pending ACK %s: %s", original_id[:8], exc)
+            return None
+
+        pending.status = AckStatus.CONFIRMED
+        pending.confirmed_at = datetime.now(timezone.utc)
+        pending.confirmed_via = ack_envelope.metadata.delivered_via
+
+        path.write_text(pending.model_dump_json(indent=2))
+        logger.info("ACK confirmed for %s from %s", original_id[:8], ack_envelope.sender)
+        return pending
+
+    def get(self, envelope_id: str) -> Optional[PendingAck]:
+        """Look up a pending ACK by envelope ID.
+
+        Args:
+            envelope_id: The original message's envelope ID.
+
+        Returns:
+            PendingAck or None if not tracked.
+        """
+        path = self._dir / f"{envelope_id}{ACK_SUFFIX}"
+        if not path.exists():
+            return None
+        try:
+            return PendingAck.model_validate_json(path.read_text())
+        except Exception as exc:
+            logger.debug("Failed to load ACK entry %s: %s", envelope_id[:8], exc)
+            return None
+
+    def list_pending(self) -> list[PendingAck]:
+        """List all ACKs still awaiting confirmation.
+
+        Returns:
+            List of PendingAck with PENDING status.
+        """
+        return [a for a in self._load_all() if a.status == AckStatus.PENDING]
+
+    def list_timed_out(self) -> list[PendingAck]:
+        """List pending ACKs that have exceeded their timeout.
+
+        Returns:
+            List of PendingAck that should have been confirmed by now.
+        """
+        return [a for a in self._load_all() if a.status == AckStatus.PENDING and a.is_expired]
+
+    def list_confirmed(self) -> list[PendingAck]:
+        """List all confirmed ACKs.
+
+        Returns:
+            List of PendingAck with CONFIRMED status.
+        """
+        return [a for a in self._load_all() if a.status == AckStatus.CONFIRMED]
+
+    def check_timeouts(self) -> list[PendingAck]:
+        """Mark expired pending ACKs as timed_out and return them.
+
+        Returns:
+            List of ACKs that just timed out.
+        """
+        newly_timed_out: list[PendingAck] = []
+        for pending in self._load_all():
+            if pending.status == AckStatus.PENDING and pending.is_expired:
+                pending.status = AckStatus.TIMED_OUT
+                path = self._dir / f"{pending.envelope_id}{ACK_SUFFIX}"
+                path.write_text(pending.model_dump_json(indent=2))
+                newly_timed_out.append(pending)
+                logger.warning("ACK timed out for %s", pending.envelope_id[:8])
+        return newly_timed_out
+
+    def purge_confirmed(self, max_age: int = 86400) -> int:
+        """Remove confirmed ACKs older than max_age seconds.
+
+        Args:
+            max_age: Maximum age in seconds for confirmed ACKs.
+
+        Returns:
+            Number of ACK files removed.
+        """
+        removed = 0
+        now = datetime.now(timezone.utc)
+        for pending in self._load_all():
+            if pending.status == AckStatus.CONFIRMED and pending.confirmed_at:
+                age = (now - pending.confirmed_at).total_seconds()
+                if age > max_age:
+                    path = self._dir / f"{pending.envelope_id}{ACK_SUFFIX}"
+                    if path.exists():
+                        path.unlink()
+                        removed += 1
+        return removed
+
+    def remove(self, envelope_id: str) -> bool:
+        """Remove an ACK tracking entry.
+
+        Args:
+            envelope_id: The original message's envelope ID.
+
+        Returns:
+            True if the entry was found and removed.
+        """
+        path = self._dir / f"{envelope_id}{ACK_SUFFIX}"
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    @property
+    def pending_count(self) -> int:
+        """Number of ACKs still pending."""
+        return len(self.list_pending())
+
+    def _load_all(self) -> list[PendingAck]:
+        """Load all ACK tracking files."""
+        results: list[PendingAck] = []
+        for path in sorted(self._dir.glob(f"*{ACK_SUFFIX}")):
+            try:
+                results.append(PendingAck.model_validate_json(path.read_text()))
+            except Exception as exc:
+                logger.warning("Skipping corrupt ACK file %s: %s", path.name, exc)
+        return results
+
+
+def should_ack(envelope: MessageEnvelope) -> bool:
+    """Check if a received envelope requests an ACK.
+
+    Args:
+        envelope: The received envelope.
+
+    Returns:
+        True if the envelope requests acknowledgment and is not itself an ACK.
+    """
+    return envelope.routing.ack_requested and not envelope.is_ack
+
+
+def make_ack_envelope(envelope: MessageEnvelope, sender: str) -> MessageEnvelope:
+    """Create an ACK envelope for a received message.
+
+    Convenience wrapper around MessageEnvelope.make_ack().
+
+    Args:
+        envelope: The received message to acknowledge.
+        sender: Our agent name (ACK sender).
+
+    Returns:
+        ACK envelope ready to send.
+    """
+    return envelope.make_ack(sender)

skcomms/adapters/__init__.py

@@ -0,0 +1,91 @@
+"""
+skcomms channel adapters (Batch C1 / C2 / C3 / C5).
+
+Platform bridges translate between a foreign platform's wire format and the
+normalized :class:`~skcomms.adapters.models.ChannelMessage`.  The
+:class:`~skcomms.adapters.registry.AdapterRegistry` manages the set of live
+adapters and enforces the P0 unified-memory contract.
+
+Public surface::
+
+    from skcomms.adapters import (
+        ChannelAdapter,
+        ChannelMessage,
+        PlatformIdentity,
+        AdapterCapabilities,
+        AdapterHealth,
+        AdapterRegistry,
+        TelegramAdapter,
+        SlackAdapter,
+        DiscordAdapter,
+        MatrixAdapter,
+        ChannelType,
+        MessageKind,
+        TrustLevel,
+    )
+
+Spec: docs/superpowers/specs/2026-06-13-skcomms-channel-adapter.md
+"""
+
+from .base import (
+    AdapterAuthError,
+    AdapterCapabilities,
+    AdapterConnectError,
+    AdapterError,
+    AdapterHealth,
+    AdapterSendError,
+    ChannelAdapter,
+)
+from .discord import DiscordAdapter
+from .factory import (
+    BUILTIN_ADAPTERS,
+    build_adapter,
+    build_registry_from_config,
+    expand_env,
+)
+from .fake import FakeAdapter
+from .matrix import MatrixAdapter
+from .models import (
+    ChannelMessage,
+    ChannelType,
+    MediaAttachment,
+    MessageKind,
+    PlatformIdentity,
+    ResolvedIdentity,
+    TrustLevel,
+)
+from .registry import AdapterRegistry
+from .slack import SlackAdapter
+from .telegram import TelegramAdapter
+
+__all__ = [
+    # ABC + health / capability models
+    "ChannelAdapter",
+    "AdapterCapabilities",
+    "AdapterHealth",
+    "AdapterError",
+    "AdapterAuthError",
+    "AdapterConnectError",
+    "AdapterSendError",
+    # Normalized message model
+    "ChannelMessage",
+    "ChannelType",
+    "MessageKind",
+    "PlatformIdentity",
+    "ResolvedIdentity",
+    "MediaAttachment",
+    "TrustLevel",
+    # Registry
+    "AdapterRegistry",
+    # Adapter implementations
+    "TelegramAdapter",
+    "SlackAdapter",
+    "DiscordAdapter",
+    "MatrixAdapter",
+    "FakeAdapter",
+    # Factory / config→registry plumbing
+    "BUILTIN_ADAPTERS",
+    "build_adapter",
+    "build_registry_from_config",
+    "expand_env",
+]

skcomms/adapters/base.py

@@ -0,0 +1,230 @@
+"""
+ChannelAdapter abstract base class (Batch C1).
+
+Every platform bridge (Telegram, Slack, Discord, NC Talk, Matrix, …) must
+implement this ABC.  The adapter owns the platform edge; the skcomms hub owns
+the interior (identity resolution, memory write, advocacy dispatch).
+
+Spec: docs/superpowers/specs/2026-06-13-skcomms-channel-adapter.md §4
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import AsyncIterator, Optional
+
+from .models import ChannelMessage, ChannelType, PlatformIdentity
+
+# ---------------------------------------------------------------------------
+# Capability / health models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AdapterCapabilities:
+    """
+    Declare what this adapter can do.
+
+    The hub uses these flags to decide whether to downgrade a rich
+    outbound message before forwarding (e.g. strip a voice note to a
+    transcript when voice_notes=False).
+    """
+
+    text: bool = True
+    files: bool = True
+    images: bool = True
+    voice_notes: bool = False
+    video: bool = False
+    reactions: bool = False
+    threads: bool = False  # inline threading (Slack threads, TG reply-chain)
+    read_receipts: bool = False
+    typing_hint: bool = False
+    max_text_bytes: int = 4096  # platform message size limit
+
+
+@dataclass
+class AdapterHealth:
+    """Point-in-time health snapshot for monitoring."""
+
+    adapter_name: str
+    connected: bool
+    latency_ms: Optional[float]
+    error: Optional[str] = None
+    queued_outbound: int = 0  # messages waiting to be delivered
+
+
+# ---------------------------------------------------------------------------
+# Custom exceptions
+# ---------------------------------------------------------------------------
+
+
+class AdapterError(Exception):
+    """Base class for all adapter errors."""
+
+
+class AdapterAuthError(AdapterError):
+    """Raised by connect() when credentials are invalid."""
+
+
+class AdapterConnectError(AdapterError):
+    """Raised by connect() when the platform is unreachable."""
+
+
+class AdapterSendError(AdapterError):
+    """Raised by send() on unrecoverable delivery failure."""
+
+
+# ---------------------------------------------------------------------------
+# ChannelAdapter ABC
+# ---------------------------------------------------------------------------
+
+
+class ChannelAdapter(ABC):
+    """
+    Abstract base class for all skcomms channel adapters.
+
+    An adapter is the thin boundary between a foreign platform (Telegram,
+    Slack, Discord, …) and the skcomms sovereign hub.  It does three things:
+
+      1. Translate inbound platform events → ChannelMessage.
+      2. Translate outbound ChannelMessage → platform API calls.
+      3. Map FQID ↔ platform user/room identities.
+
+    It does NOT:
+      - Write to skmem-pg directly.
+      - Resolve FQID trust levels (that is the hub's job).
+      - Hold conversation state beyond what the platform provides.
+      - Know about CapAuth keys.
+
+    Lifecycle::
+
+        adapter = TelegramAdapter(config)
+        await adapter.connect()              # authenticate + start polling/webhook
+        async for msg in adapter.inbound():  # yields normalized ChannelMessages
+            await hub.dispatch_inbound(msg)
+        await adapter.disconnect()
+
+    Subclasses must set the class-level ``channel_type`` and ``adapter_name``
+    attributes (not enforced by the ABC machinery so that ``__init_subclass__``
+    stays simple, but validated at runtime by the registry).
+    """
+
+    # Subclasses must set these:
+    channel_type: ChannelType
+    adapter_name: str  # e.g. "telegram", "slack-sktechops"
+
+    # -----------------------------------------------------------------------
+    # Lifecycle
+    # -----------------------------------------------------------------------
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """
+        Authenticate with the platform and start the inbound loop.
+
+        Raises:
+            AdapterAuthError: If credentials are invalid.
+            AdapterConnectError: If the platform is unreachable.
+        """
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Gracefully stop the inbound loop and close any open connections."""
+
+    @abstractmethod
+    async def health(self) -> AdapterHealth:
+        """
+        Return a point-in-time health snapshot.
+
+        Called by the adapter registry every 30 s; used by skmon and
+        the ``skcomms adapter status`` CLI subcommand.
+        """
+
+    # -----------------------------------------------------------------------
+    # Inbound (platform → skcomms)
+    # -----------------------------------------------------------------------
+
+    @abstractmethod
+    async def inbound(self) -> AsyncIterator[ChannelMessage]:
+        """
+        Async generator that yields normalized ChannelMessages as they arrive.
+
+        The hub calls ``async for msg in adapter.inbound(): …``.
+        Implementations may use long-polling, webhooks, or WebSocket
+        subscriptions — the caller does not care which.
+
+        Yields:
+            ChannelMessage: one per platform event.
+        """
+
+    # -----------------------------------------------------------------------
+    # Outbound (skcomms → platform)
+    # -----------------------------------------------------------------------
+
+    @abstractmethod
+    async def send(self, message: ChannelMessage) -> str:
+        """
+        Deliver a ChannelMessage to the platform.
+
+        The hub calls this after resolving the outbound route.  Must handle
+        rate limiting internally (back off + retry up to the adapter's
+        configured timeout, then raise AdapterSendError).
+
+        Args:
+            message: Normalized outbound message.  The hub has already applied
+                     capability downgrade (e.g. converted voice to a transcript
+                     if voice_notes=False).
+
+        Returns:
+            The platform's message id for the delivered message (str).
+
+        Raises:
+            AdapterSendError: On unrecoverable failure.
+        """
+
+    # -----------------------------------------------------------------------
+    # Identity mapping (FQID ↔ platform user/room)
+    # -----------------------------------------------------------------------
+
+    @abstractmethod
+    async def resolve_fqid(self, platform_id: PlatformIdentity) -> Optional[str]:
+        """
+        Look up the FQID bound to this platform identity.
+
+        Returns the FQID string (e.g. "chef@skworld.io") if a verified binding
+        exists, or None if the platform user is unknown.
+
+        The hub calls this on every inbound message and assigns a trust level
+        accordingly.  Implementations should consult the adapter's local
+        identity map first, then optionally query the CapAuth DID registry.
+        """
+
+    @abstractmethod
+    async def bind_fqid(
+        self,
+        platform_id: PlatformIdentity,
+        fqid: str,
+        trust_level: str,
+    ) -> None:
+        """
+        Persist a verified FQID ↔ platform-id binding.
+
+        Called by the hub's identity-binding flow (e.g. when Chef types
+        ``/bind chef@skworld.io`` in the Telegram group and the hub verifies
+        the CapAuth challenge).  Implementations write to the adapter's own
+        store (YAML / SQLite / skcapstone peers/).
+        """
+
+    # -----------------------------------------------------------------------
+    # Capabilities declaration (not abstract — safe default provided)
+    # -----------------------------------------------------------------------
+
+    def capabilities(self) -> AdapterCapabilities:
+        """
+        Declare what this platform supports.
+
+        Subclasses should override to return accurate flags.
+        The hub uses these for outbound capability downgrade.
+        """
+        return AdapterCapabilities()