@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/connectors/registry.py

@@ -0,0 +1,254 @@
+"""
+ConnectorRegistry — discover and instantiate platform connectors.
+
+Maintains a catalogue of every known ConnectorBackend class and can
+probe each one to report which platforms are currently reachable.
+
+Built-in connectors are always registered.  Third-party connectors can
+be registered at runtime via register().
+
+Usage::
+
+    registry = ConnectorRegistry()
+    available = registry.available()          # only CONNECTED/DISCONNECTED
+    connector = registry.create("terminal")   # instantiate by type name
+    connector.connect()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List, Optional, Tuple, Type
+
+from .base import ConnectorBackend, ConnectorInfo, ConnectorStatus, ConnectorType
+from .cursor import CursorConnector
+from .terminal import TerminalConnector
+from .vscode import VSCodeConnector
+
+logger = logging.getLogger(__name__)
+
+# Built-in connector classes indexed by ConnectorType value
+_BUILTIN_CONNECTORS: Dict[str, Type[ConnectorBackend]] = {
+    ConnectorType.TERMINAL.value: TerminalConnector,
+    ConnectorType.VSCODE.value: VSCodeConnector,
+    ConnectorType.CURSOR.value: CursorConnector,
+}
+
+
+class ConnectorRegistry:
+    """Catalogue of sovereign agent platform connectors.
+
+    Probes each registered connector to determine which platforms are
+    currently reachable without establishing a persistent connection.
+
+    ``start_all()`` / ``stop_all()`` provide a simple lifecycle API: they
+    instantiate every registered connector, call ``connect()`` / ``disconnect()``
+    on each one, and keep the live instances in an internal table so that
+    callers can retrieve them later.
+
+    Args:
+        auto_register_builtins: If True (default), pre-populate with all
+            built-in connectors on construction.
+    """
+
+    def __init__(self, auto_register_builtins: bool = True) -> None:
+        self._registry: Dict[str, Type[ConnectorBackend]] = {}
+        self._running: Dict[str, ConnectorBackend] = {}
+        if auto_register_builtins:
+            self._registry.update(_BUILTIN_CONNECTORS)
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        connector_class: Type[ConnectorBackend],
+    ) -> None:
+        """Register a connector class under a given name.
+
+        Overwrites any existing entry with the same name.
+
+        Args:
+            name: Lookup key (e.g. ConnectorType value or custom slug).
+            connector_class: Class that implements ConnectorBackend.
+        """
+        self._registry[name] = connector_class
+        logger.debug("Registered connector: %s -> %s", name, connector_class.__name__)
+
+    def unregister(self, name: str) -> bool:
+        """Remove a connector from the registry.
+
+        Args:
+            name: The key used when the connector was registered.
+
+        Returns:
+            True if the key existed and was removed, False otherwise.
+        """
+        if name in self._registry:
+            del self._registry[name]
+            return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Discovery
+    # ------------------------------------------------------------------
+
+    def list_names(self) -> List[str]:
+        """Return the names of all registered connectors.
+
+        Returns:
+            Sorted list of connector name strings.
+        """
+        return sorted(self._registry.keys())
+
+    def probe(self) -> List[ConnectorInfo]:
+        """Probe all registered connectors and return their status snapshots.
+
+        Each probe instantiates the connector with default args and calls
+        health_check() — no persistent connection is established.
+
+        Returns:
+            List of ConnectorInfo objects sorted by connector name.
+        """
+        results: List[ConnectorInfo] = []
+        for name, cls in sorted(self._registry.items()):
+            try:
+                instance = cls()
+                status = instance.health_check()
+                results.append(
+                    ConnectorInfo(
+                        name=name,
+                        connector_type=instance.connector_type,
+                        status=status,
+                    )
+                )
+            except Exception as exc:
+                logger.warning("probe: error checking %s: %s", name, exc)
+                results.append(
+                    ConnectorInfo(
+                        name=name,
+                        connector_type=ConnectorType.UNKNOWN,
+                        status=ConnectorStatus.ERROR,
+                        metadata={"error": str(exc)},
+                    )
+                )
+        return results
+
+    def available(self) -> List[ConnectorInfo]:
+        """Return only connectors that are not UNAVAILABLE or in ERROR.
+
+        Returns:
+            Subset of probe() results where status is CONNECTED or DISCONNECTED.
+        """
+        return [
+            info
+            for info in self.probe()
+            if info.status not in (ConnectorStatus.UNAVAILABLE, ConnectorStatus.ERROR)
+        ]
+
+    # ------------------------------------------------------------------
+    # Instantiation
+    # ------------------------------------------------------------------
+
+    def create(
+        self,
+        name: str,
+        **kwargs: object,
+    ) -> Optional[ConnectorBackend]:
+        """Instantiate a connector by its registered name.
+
+        Args:
+            name: Connector name as returned by list_names().
+            **kwargs: Forwarded to the connector's __init__.
+
+        Returns:
+            New ConnectorBackend instance, or None if name is not registered.
+        """
+        cls = self._registry.get(name)
+        if cls is None:
+            logger.warning("ConnectorRegistry.create: unknown connector %r", name)
+            return None
+        return cls(**kwargs)
+
+    def get_class(self, name: str) -> Optional[Type[ConnectorBackend]]:
+        """Return the connector class registered under name, without instantiating.
+
+        Args:
+            name: Connector name.
+
+        Returns:
+            ConnectorBackend subclass, or None if not found.
+        """
+        return self._registry.get(name)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start_all(self, **kwargs: object) -> List[Tuple[str, bool]]:
+        """Instantiate and connect every registered connector.
+
+        Already-running connectors (present in the internal running table)
+        are skipped — call ``stop_all()`` first to restart them.
+
+        Args:
+            **kwargs: Forwarded to each connector's ``__init__`` where accepted.
+                Most built-in connectors take no extra arguments, so omit this
+                in normal usage.
+
+        Returns:
+            List of ``(name, success)`` tuples in registry order, where
+            ``success`` is the return value of ``connect()``.
+        """
+        results: List[Tuple[str, bool]] = []
+        for name, cls in sorted(self._registry.items()):
+            if name in self._running:
+                logger.debug("start_all: %s is already running — skipping", name)
+                results.append((name, True))
+                continue
+            try:
+                instance = cls(**kwargs)
+                ok = instance.connect()
+                if ok:
+                    self._running[name] = instance
+                    logger.info("start_all: %s connected", name)
+                else:
+                    logger.warning("start_all: %s connect() returned False", name)
+                results.append((name, ok))
+            except Exception as exc:
+                logger.error("start_all: %s raised %s", name, exc)
+                results.append((name, False))
+        return results
+
+    def stop_all(self) -> List[Tuple[str, bool]]:
+        """Disconnect and remove every running connector instance.
+
+        Returns:
+            List of ``(name, success)`` tuples where ``success`` is the
+            return value of ``disconnect()``.
+        """
+        results: List[Tuple[str, bool]] = []
+        for name, instance in list(self._running.items()):
+            try:
+                ok = instance.disconnect()
+                logger.info("stop_all: %s disconnected (ok=%s)", name, ok)
+                results.append((name, ok))
+            except Exception as exc:
+                logger.error("stop_all: %s raised %s", name, exc)
+                results.append((name, False))
+            finally:
+                self._running.pop(name, None)
+        return results
+
+    def get_running(self, name: str) -> Optional[ConnectorBackend]:
+        """Return the live connector instance for *name*, if started.
+
+        Args:
+            name: Connector name as returned by ``list_names()``.
+
+        Returns:
+            Running ConnectorBackend instance, or None if not started.
+        """
+        return self._running.get(name)

package/src/skcapstone/connectors/terminal.py

@@ -0,0 +1,152 @@
+"""
+TerminalConnector — sovereign agent viewport over stdin/stdout.
+
+The terminal is the primordial interface: no extension required, no
+network needed.  Messages are written to stdout and read from a queue
+fed by a background reader thread on stdin.
+
+Thread safety:
+- A daemon thread reads stdin lines and enqueues them.
+- send() writes directly to the output stream (default: sys.stdout).
+- receive() pops from the queue (non-blocking).
+"""
+
+from __future__ import annotations
+
+import queue
+import sys
+import threading
+from io import TextIOBase
+from typing import Optional, TextIO
+
+from .base import ConnectorBackend, ConnectorStatus, ConnectorType
+
+
+class TerminalConnector(ConnectorBackend):
+    """Read from stdin, write to stdout — the always-available channel.
+
+    Args:
+        input_stream: Readable text stream (default: sys.stdin).
+        output_stream: Writable text stream (default: sys.stdout).
+        prompt: Optional prompt string written before each received line.
+    """
+
+    connector_type = ConnectorType.TERMINAL
+
+    def __init__(
+        self,
+        input_stream: Optional[TextIO] = None,
+        output_stream: Optional[TextIO] = None,
+        prompt: str = "",
+    ) -> None:
+        self._input: TextIO = input_stream or sys.stdin
+        self._output: TextIO = output_stream or sys.stdout
+        self._prompt = prompt
+        self._queue: queue.Queue[str] = queue.Queue()
+        self._reader: Optional[threading.Thread] = None
+        self._connected = False
+        self._error: Optional[str] = None
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def connect(self) -> bool:
+        """Start the background stdin reader thread.
+
+        Returns:
+            True if connected (idempotent — safe to call multiple times).
+        """
+        if self._connected:
+            return True
+
+        self._error = None
+        self._reader = threading.Thread(
+            target=self._read_loop,
+            name="terminal-connector-reader",
+            daemon=True,
+        )
+        self._reader.start()
+        self._connected = True
+        return True
+
+    def disconnect(self) -> bool:
+        """Mark the connector as disconnected.
+
+        The background reader thread will exit naturally when stdin closes.
+
+        Returns:
+            True always.
+        """
+        self._connected = False
+        return True
+
+    # ------------------------------------------------------------------
+    # Messaging
+    # ------------------------------------------------------------------
+
+    def send(self, message: str) -> bool:
+        """Write a message to the output stream.
+
+        Args:
+            message: Text to write.  A trailing newline is appended if
+                     not already present.
+
+        Returns:
+            True if written successfully, False on I/O error.
+        """
+        if not self._connected:
+            return False
+        try:
+            if self._prompt:
+                self._output.write(self._prompt)
+            if not message.endswith("\n"):
+                message = message + "\n"
+            self._output.write(message)
+            self._output.flush()
+            return True
+        except OSError as exc:
+            self._error = str(exc)
+            return False
+
+    def receive(self) -> Optional[str]:
+        """Return the next queued line from stdin (non-blocking).
+
+        Returns:
+            Line string (without trailing newline) or None if the queue
+            is empty.
+        """
+        try:
+            return self._queue.get_nowait()
+        except queue.Empty:
+            return None
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    def health_check(self) -> ConnectorStatus:
+        """Return connector status based on connection state and errors.
+
+        Returns:
+            CONNECTED, DISCONNECTED, or ERROR.
+        """
+        if self._error:
+            return ConnectorStatus.ERROR
+        if not self._connected:
+            return ConnectorStatus.DISCONNECTED
+        return ConnectorStatus.CONNECTED
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _read_loop(self) -> None:
+        """Background thread: read lines from stdin and enqueue them."""
+        try:
+            for line in self._input:
+                if not self._connected:
+                    break
+                self._queue.put(line.rstrip("\n"))
+        except OSError as exc:
+            self._error = str(exc)

package/src/skcapstone/connectors/vscode.py

@@ -0,0 +1,60 @@
+"""
+VSCodeConnector — sovereign agent viewport into Visual Studio Code.
+
+Communicates with the SKCapstone VS Code extension via a Unix domain socket
+at ``~/.skcapstone/connectors/vscode.sock``.
+
+Protocol
+--------
+The agent is the **server**.  On ``connect()`` it creates and binds the socket
+so the VS Code extension (client) can connect at any time.
+
+Wire format: 4-byte big-endian uint32 length prefix + UTF-8 JSON-RPC 2.0 body.
+See :class:`~skcapstone.connectors.base.UnixSocketConnector` for details.
+
+Extension contract:
+  - Extension connects to ``~/.skcapstone/connectors/vscode.sock``.
+  - Both sides exchange length-framed JSON-RPC 2.0 messages.
+  - Notifications (no ``"id"`` field) are fire-and-forget.
+  - Requests carry an ``"id"`` and expect a matching ``"result"`` response.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .base import ConnectorStatus, ConnectorType, UnixSocketConnector
+
+_DEFAULT_SOCKET_PATH = Path("~/.skcapstone/connectors/vscode.sock")
+
+
+class VSCodeConnector(UnixSocketConnector):
+    """Connect the sovereign agent to Visual Studio Code.
+
+    Binds a Unix domain socket at ``~/.skcapstone/connectors/vscode.sock``
+    and waits for the SKCapstone VS Code extension to connect.
+
+    Args:
+        socket_path: Override the default socket file location.
+    """
+
+    connector_type = ConnectorType.VSCODE
+
+    def __init__(self, socket_path: Optional[Path] = None) -> None:
+        super().__init__(socket_path or _DEFAULT_SOCKET_PATH)
+
+    # health_check is inherited — returns UNAVAILABLE only if _connected is False
+    # and no error; override to surface UNAVAILABLE while socket dir is absent
+    # so that registry.probe() can distinguish "never started" from "disconnected".
+
+    def health_check(self) -> ConnectorStatus:
+        """Return the current connector status.
+
+        Returns UNAVAILABLE when neither connected nor the socket dir exists,
+        so callers can tell whether the extension has ever been set up.
+        """
+        status = super().health_check()
+        if status == ConnectorStatus.DISCONNECTED and not self._socket_path.parent.exists():
+            return ConnectorStatus.UNAVAILABLE
+        return status

package/src/skcapstone/consciousness_config.py

@@ -0,0 +1,119 @@
+"""
+Consciousness configuration loader.
+
+Loads ConsciousnessConfig from YAML with override hierarchy:
+    1. Per-agent config: {agent_home}/config/consciousness.yaml
+    2. Environment: SKCAPSTONE_CONSCIOUSNESS_ENABLED=false
+    3. CLI flag: --no-consciousness
+
+Usage:
+    config = load_consciousness_config(home)
+    config = load_consciousness_config(home, cli_disabled=True)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .consciousness_loop import ConsciousnessConfig
+
+logger = logging.getLogger("skcapstone.consciousness_config")
+
+CONFIG_FILENAME = "consciousness.yaml"
+
+
+def load_consciousness_config(
+    home: Path,
+    cli_disabled: bool = False,
+    config_path: Optional[Path] = None,
+) -> ConsciousnessConfig:
+    """Load consciousness config with override hierarchy.
+
+    Priority (highest wins):
+        1. CLI flag (--no-consciousness)
+        2. Environment variable (SKCAPSTONE_CONSCIOUSNESS_ENABLED)
+        3. YAML config file
+        4. Defaults
+
+    Args:
+        home: Agent home directory.
+        cli_disabled: True if --no-consciousness was passed.
+        config_path: Explicit path to config file (overrides default).
+
+    Returns:
+        Resolved ConsciousnessConfig.
+    """
+    config = ConsciousnessConfig()
+
+    # Load from YAML
+    yaml_path = config_path or (home / "config" / CONFIG_FILENAME)
+    if yaml_path.exists():
+        try:
+            raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+            if raw and isinstance(raw, dict):
+                config = ConsciousnessConfig.model_validate(raw)
+                logger.info("Loaded consciousness config from %s", yaml_path)
+        except Exception as exc:
+            logger.warning(
+                "Failed to parse %s, using defaults: %s", yaml_path, exc
+            )
+
+    # Environment override
+    env_enabled = os.environ.get("SKCAPSTONE_CONSCIOUSNESS_ENABLED", "").lower()
+    if env_enabled == "false":
+        config.enabled = False
+        logger.info("Consciousness disabled via SKCAPSTONE_CONSCIOUSNESS_ENABLED")
+    elif env_enabled == "true":
+        config.enabled = True
+
+    # CLI override (highest priority)
+    if cli_disabled:
+        config.enabled = False
+        logger.info("Consciousness disabled via --no-consciousness flag")
+
+    return config
+
+
+def write_default_config(home: Path) -> Path:
+    """Write the default consciousness config to disk.
+
+    Creates {home}/config/consciousness.yaml with all defaults
+    commented for reference.
+
+    Args:
+        home: Agent home directory.
+
+    Returns:
+        Path to the created config file.
+    """
+    config_dir = home / "config"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path = config_dir / CONFIG_FILENAME
+
+    default = ConsciousnessConfig()
+    content = yaml.dump(
+        default.model_dump(),
+        default_flow_style=False,
+        sort_keys=False,
+    )
+
+    header = (
+        "# Consciousness Loop Configuration\n"
+        "#\n"
+        "# Override hierarchy:\n"
+        "#   1. CLI: skcapstone daemon start --no-consciousness\n"
+        "#   2. Env: SKCAPSTONE_CONSCIOUSNESS_ENABLED=false\n"
+        "#   3. This file\n"
+        "#\n"
+        "# See: skcapstone consciousness config --show\n"
+        "\n"
+    )
+
+    config_path.write_text(header + content, encoding="utf-8")
+    logger.info("Wrote default consciousness config to %s", config_path)
+    return config_path