ariadex 0.1.0__py3-none-any.whl

ariadex/__init__.py

@@ -0,0 +1,3 @@
+"""Ariadex: human-supervised runtime for long-running AI coding workflows."""
+
+__version__ = "0.1.0"

ariadex/__main__.py

@@ -0,0 +1,6 @@
+"""Run the Ariadex CLI: `python -m ariadex <command>`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ariadex/adapters.py

@@ -0,0 +1,190 @@
+"""Provider-neutral agent lifecycle contract and capability model.
+
+`AgentAdapter` owns provider command construction and lifecycle mapping:
+start, send, interrupt, new session, output capture, idle detection, and
+terminate. It never embeds terminal transport details (those belong to
+`TerminalDriver`) and never calls an LLM API.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+from pathlib import Path
+
+from . import terminal as terminal_mod
+
+
+@dataclasses.dataclass(frozen=True)
+class Capabilities:
+    """Inspectable adapter capabilities consumed by the runner."""
+
+    interactive: bool = True
+    soft_reset: bool = False
+    hard_reset: bool = True
+    token_usage: bool = False
+    structured_output: bool = False
+    interrupt: bool = True
+    manual_takeover: bool = True
+
+
+class AdapterError(Exception):
+    """Base class for typed adapter failures."""
+
+
+class UnsupportedOperation(AdapterError):
+    """The adapter explicitly does not support the requested operation."""
+
+
+class StartupError(AdapterError):
+    """Provider startup failed."""
+
+
+class TransportError(AdapterError):
+    """Input delivery to a running provider failed."""
+
+
+class CaptureError(AdapterError):
+    """Output capture from a running provider failed."""
+
+
+class TerminationError(AdapterError):
+    """Provider termination failed."""
+
+
+def select_reset(reset_mode: str, capabilities: Capabilities) -> str:
+    """Choose `soft` or `hard` reset from declared capabilities.
+
+    `auto` selects the strongest supported operation, preferring soft reset
+    when available. Raises UnsupportedOperation when the requested strength
+    is not declared.
+    """
+    if reset_mode == "soft":
+        if not capabilities.soft_reset:
+            raise UnsupportedOperation("adapter lacks `soft_reset` capability")
+        return "soft"
+    if reset_mode == "hard":
+        if not capabilities.hard_reset:
+            raise UnsupportedOperation("adapter lacks `hard_reset` capability")
+        return "hard"
+    if reset_mode == "auto":
+        if capabilities.soft_reset:
+            return "soft"
+        if capabilities.hard_reset:
+            return "hard"
+        raise UnsupportedOperation(
+            "adapter declares neither `soft_reset` nor `hard_reset`"
+        )
+    raise AdapterError(
+        f"invalid reset mode `{reset_mode}`: expected soft, hard, or auto"
+    )
+
+
+class AgentAdapter(abc.ABC):
+    """One lifecycle contract implemented per Coding CLI provider."""
+
+    provider_name: str = "unknown"
+    launch_command: tuple[str, ...] = ()
+    new_session_input: str | None = None
+
+    def __init__(
+        self,
+        driver: terminal_mod.TerminalDriver,
+        session_name: str,
+        workdir: Path | str,
+    ) -> None:
+        self.driver = driver
+        self.session_name = session_name
+        self.workdir = workdir
+
+    @property
+    @abc.abstractmethod
+    def capabilities(self) -> Capabilities:
+        """Declared capabilities; the runner must consult these."""
+
+    def start(self) -> str:
+        """Create or connect the session and launch the provider.
+
+        Returns `created` or `connected`. Wraps driver failures so callers
+        only handle AdapterError.
+        """
+        try:
+            return self.driver.create_or_connect(
+                self.session_name, self.workdir, list(self.launch_command)
+            )
+        except terminal_mod.TerminalError as exc:
+            raise StartupError(f"{self.provider_name} startup failed: {exc}") from exc
+
+    def send(self, text: str) -> None:
+        try:
+            self.driver.send_input(self.session_name, text)
+        except terminal_mod.TmuxNotAvailable as exc:
+            raise TransportError(str(exc)) from exc
+        except terminal_mod.SessionMissing as exc:
+            raise TransportError(str(exc)) from exc
+        except terminal_mod.TerminalError as exc:
+            raise TransportError(
+                f"failed to deliver input to {self.provider_name}: {exc}"
+            ) from exc
+
+    def interrupt(self) -> None:
+        if not self.capabilities.interrupt:
+            raise UnsupportedOperation(
+                f"{self.provider_name} lacks `interrupt` capability"
+            )
+        try:
+            self.driver.interrupt(self.session_name)
+        except terminal_mod.TerminalError as exc:
+            raise TransportError(
+                f"failed to interrupt {self.provider_name}: {exc}"
+            ) from exc
+
+    def new_session(self) -> None:
+        """Soft reset via the provider's new-session input.
+
+        Reports the missing capability so the runner can fall back to hard
+        reset (terminate and restart) instead of assuming `/new` works.
+        """
+        if not self.capabilities.soft_reset or self.new_session_input is None:
+            raise UnsupportedOperation(
+                f"{self.provider_name} lacks `soft_reset` capability; "
+                "use hard reset (terminate and restart)"
+            )
+        try:
+            self.driver.send_input(self.session_name, self.new_session_input)
+        except terminal_mod.TerminalError as exc:
+            raise TransportError(
+                f"failed to reset {self.provider_name} session: {exc}"
+            ) from exc
+
+    def capture_output(self) -> str:
+        """Return raw pane output verbatim for the logger.
+
+        Never interprets provider text as completion.
+        """
+        try:
+            return self.driver.capture(self.session_name)
+        except terminal_mod.TerminalError as exc:
+            raise CaptureError(
+                f"failed to capture {self.provider_name} output: {exc}"
+            ) from exc
+
+    def is_idle(self) -> bool:
+        """Conservative default: never claim idle without evidence."""
+        return False
+
+    def get_usage(self) -> dict | None:
+        """Provider token/cost usage, or None when not exposed.
+
+        Metrics must record `usage: unavailable` in that case and never
+        invent an estimate.
+        """
+        return None
+
+    def terminate(self) -> None:
+        try:
+            self.driver.terminate(self.session_name)
+        except terminal_mod.TerminalError as exc:
+            raise TerminationError(
+                f"failed to terminate {self.provider_name}: {exc}"
+            ) from exc