tactus 0.32.2__py3-none-any.whl → 0.34.0__py3-none-any.whl

tactus/adapters/channels/host.py

@@ -0,0 +1,225 @@
+"""
+Host app control channel base class.
+
+Provides the pattern for any app embedding Tactus to become a control channel.
+The CLI is the simplest example, but this applies to any host app: web servers,
+desktop apps, Jupyter notebooks, etc.
+
+Key features:
+- Interruptible via background thread pattern
+- Can be cancelled if another channel responds first
+- Races with remote channels - first response wins
+"""
+
+import asyncio
+import logging
+import threading
+from abc import abstractmethod
+from typing import Optional
+from datetime import datetime, timezone
+
+from tactus.protocols.control import (
+    ControlRequest,
+    ControlResponse,
+    ChannelCapabilities,
+    DeliveryResult,
+)
+from tactus.adapters.channels.base import InProcessChannel
+
+logger = logging.getLogger(__name__)
+
+
+class HostControlChannel(InProcessChannel):
+    """
+    Base class for host app control channels.
+
+    Any app embedding Tactus can extend this to become a control channel.
+    The channel uses a background thread for input collection so it can
+    be interrupted if another channel responds first.
+
+    Subclasses must implement:
+    - _prompt_for_input(): Display prompt and collect input (runs in thread)
+    - _show_cancelled(): Display cancellation message
+
+    The background thread pattern:
+    1. send() displays the request and starts a background thread
+    2. Thread calls _prompt_for_input() which blocks on user input
+    3. If input received, push_response() adds to queue
+    4. If cancel() called first, thread is interrupted via _cancel_event
+    5. _show_cancelled() displays "Responded via {channel}" message
+    """
+
+    def __init__(self):
+        """Initialize the host channel."""
+        super().__init__()
+        self._cancel_event = threading.Event()
+        self._input_thread: Optional[threading.Thread] = None
+        self._current_request: Optional[ControlRequest] = None
+        self._event_loop: Optional[asyncio.AbstractEventLoop] = None
+
+    @property
+    def capabilities(self) -> ChannelCapabilities:
+        """Host channels support immediate synchronous responses."""
+        return ChannelCapabilities(
+            supports_approval=True,
+            supports_input=True,
+            supports_review=True,
+            supports_escalation=True,
+            supports_interactive_buttons=False,
+            supports_file_attachments=False,
+            max_message_length=None,
+            is_synchronous=True,
+        )
+
+    async def send(self, request: ControlRequest) -> DeliveryResult:
+        """
+        Display the request and start background input collection.
+
+        The actual prompt is displayed and input collected in a background
+        thread so we can be interrupted if another channel responds first.
+
+        Args:
+            request: ControlRequest with full context
+
+        Returns:
+            DeliveryResult indicating successful delivery
+        """
+        logger.info(f"{self.channel_id}: sending notification for {request.request_id}")
+
+        # Store for background thread access
+        self._current_request = request
+        self._cancel_event.clear()
+
+        # Capture event loop for thread-safe response pushing
+        self._event_loop = asyncio.get_event_loop()
+
+        # Display the request (synchronous, before starting thread)
+        self._display_request(request)
+
+        # Start background thread for input collection
+        self._input_thread = threading.Thread(
+            target=self._input_thread_main,
+            args=(request,),
+            daemon=True,
+        )
+        self._input_thread.start()
+
+        return DeliveryResult(
+            channel_id=self.channel_id,
+            external_message_id=request.request_id,
+            delivered_at=datetime.now(timezone.utc),
+            success=True,
+        )
+
+    async def cancel(self, external_message_id: str, reason: str) -> None:
+        """
+        Cancel the prompt - another channel responded first.
+
+        Sets the cancel event to interrupt the background thread,
+        then displays a message indicating another channel responded.
+
+        Args:
+            external_message_id: Request ID (same as sent)
+            reason: Reason for cancellation (e.g., "Responded via tactus_cloud")
+        """
+        logger.debug(f"{self.channel_id}: cancelling {external_message_id}: {reason}")
+        self._cancel_event.set()
+        self._show_cancelled(reason)
+
+    async def shutdown(self) -> None:
+        """Clean shutdown - cancel any pending input."""
+        await super().shutdown()
+        self._cancel_event.set()
+        if self._input_thread and self._input_thread.is_alive():
+            self._input_thread.join(timeout=1.0)
+
+    def _input_thread_main(self, request: ControlRequest) -> None:
+        """
+        Background thread main function.
+
+        Collects input from the user and pushes the response to the queue.
+        Can be interrupted via _cancel_event.
+
+        Args:
+            request: The control request to handle
+        """
+        try:
+            # Collect input (may block)
+            response_value = self._prompt_for_input(request)
+
+            # Check if cancelled while waiting
+            if self._cancel_event.is_set():
+                return
+
+            if response_value is not None:
+                # Create response and push to queue
+                response = ControlResponse(
+                    request_id=request.request_id,
+                    value=response_value,
+                    responded_at=datetime.now(timezone.utc),
+                    timed_out=False,
+                    channel_id=self.channel_id,
+                )
+
+                # Push thread-safe
+                if self._event_loop:
+                    self.push_response_threadsafe(response, self._event_loop)
+                else:
+                    self.push_response(response)
+
+        except Exception as e:
+            if not self._cancel_event.is_set():
+                logger.error(f"{self.channel_id}: input error: {e}")
+
+    @abstractmethod
+    def _display_request(self, request: ControlRequest) -> None:
+        """
+        Display the control request to the user.
+
+        Called synchronously before starting input thread.
+        Should display the message, options, context, etc.
+
+        Args:
+            request: The control request to display
+        """
+        ...
+
+    @abstractmethod
+    def _prompt_for_input(self, request: ControlRequest) -> Optional[any]:
+        """
+        Collect input from the user.
+
+        Runs in a background thread. Should check _cancel_event periodically
+        if blocking on long operations. Returns None if cancelled.
+
+        Args:
+            request: The control request being handled
+
+        Returns:
+            The user's response value, or None if cancelled/interrupted
+        """
+        ...
+
+    @abstractmethod
+    def _show_cancelled(self, reason: str) -> None:
+        """
+        Show cancellation message.
+
+        Called when another channel responds first.
+
+        Args:
+            reason: Reason for cancellation (e.g., "Responded via tactus_cloud")
+        """
+        ...
+
+    def is_cancelled(self) -> bool:
+        """
+        Check if the current request has been cancelled.
+
+        Call this periodically from _prompt_for_input() if your input
+        method supports checking for interruption.
+
+        Returns:
+            True if cancelled, False otherwise
+        """
+        return self._cancel_event.is_set()

tactus/adapters/channels/ipc.py

@@ -0,0 +1,297 @@
+"""
+IPC Control Channel - Unix socket communication for control loop.
+
+This channel allows external control CLI apps to connect and respond to
+control requests via Unix domain sockets using the broker protocol.
+"""
+
+import asyncio
+import logging
+import os
+import uuid
+from datetime import datetime
+from typing import Dict, Optional
+
+from tactus.broker.protocol import read_message, write_message
+from tactus.protocols.control import (
+    ControlRequest,
+    ControlResponse,
+    ChannelCapabilities,
+    DeliveryResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class IPCControlChannel:
+    """
+    Control channel using Unix socket IPC with broker protocol.
+
+    The runtime creates a Unix socket server that control CLI clients can
+    connect to. Control requests are broadcast to all connected clients,
+    and the first response wins (standard racing pattern).
+    """
+
+    def __init__(self, socket_path: Optional[str] = None, procedure_id: Optional[str] = None):
+        """
+        Initialize IPC control channel.
+
+        Args:
+            socket_path: Path to Unix socket (default: /tmp/tactus-control-{procedure_id}.sock)
+            procedure_id: Procedure ID for default socket path
+        """
+        self.procedure_id = procedure_id or "default"
+        self.socket_path = socket_path or f"/tmp/tactus-control-{self.procedure_id}.sock"
+        self.channel_id = "ipc"
+
+        self._server: Optional[asyncio.Server] = None
+        self._clients: Dict[str, asyncio.StreamWriter] = {}  # client_id -> writer
+        self._response_queue: asyncio.Queue[ControlResponse] = asyncio.Queue()
+        self._pending_requests: Dict[str, ControlRequest] = {}  # request_id -> request
+        self._initialized = False
+
+    @property
+    def capabilities(self) -> ChannelCapabilities:
+        """IPC supports all request types and can respond synchronously."""
+        return ChannelCapabilities(
+            supports_approval=True,
+            supports_input=True,
+            supports_choice=True,
+            supports_review=True,
+            supports_escalation=True,
+            is_synchronous=True,  # Humans respond in real-time via control CLI
+        )
+
+    async def initialize(self) -> None:
+        """Start Unix socket server and accept connections."""
+        if self._initialized:
+            return
+
+        logger.info(f"{self.channel_id}: initializing...")
+
+        # Remove old socket file if it exists
+        if os.path.exists(self.socket_path):
+            os.unlink(self.socket_path)
+
+        # Create parent directory if needed
+        socket_dir = os.path.dirname(self.socket_path)
+        os.makedirs(socket_dir, exist_ok=True)
+
+        # Start Unix socket server
+        self._server = await asyncio.start_unix_server(self._handle_client, path=self.socket_path)
+
+        # Set socket permissions
+        os.chmod(self.socket_path, 0o600)
+
+        self._initialized = True
+        logger.info(f"{self.channel_id}: ready (listening on {self.socket_path})")
+
+    async def send(self, request: ControlRequest) -> DeliveryResult:
+        """
+        Send control request to all connected clients.
+
+        Args:
+            request: ControlRequest object with all request details
+
+        Returns:
+            DeliveryResult with success/failure info
+        """
+        logger.info(f"{self.channel_id}: sending notification for {request.request_id}")
+
+        # Create control request message from ControlRequest object
+        request_data = {
+            "type": "control.request",
+            "request_id": request.request_id,
+            "procedure_id": request.procedure_id,
+            "procedure_name": request.procedure_name,
+            "invocation_id": request.invocation_id,
+            "request_type": request.request_type,
+            "message": request.message,
+            "options": [{"label": opt.label, "value": opt.value} for opt in request.options],
+            "default_value": request.default_value,
+            "timeout_seconds": request.timeout_seconds,
+            "metadata": request.metadata,
+            "namespace": request.namespace,
+            "subject": request.subject,
+            "started_at": request.started_at.isoformat() if request.started_at else None,
+            "input_summary": request.input_summary,
+            "conversation": request.conversation,
+            "prior_interactions": request.prior_interactions,
+        }
+
+        # Store pending request
+        self._pending_requests[request.request_id] = request_data
+
+        # Send to all connected clients
+        successful = 0
+        failed = 0
+
+        for client_id, writer in list(self._clients.items()):
+            try:
+                await write_message(writer, request_data)
+                successful += 1
+            except Exception as e:
+                logger.error(f"{self.channel_id}: failed to send to client {client_id}: {e}")
+                failed += 1
+                # Remove dead client
+                self._clients.pop(client_id, None)
+
+        if successful == 0 and len(self._clients) == 0:
+            logger.warning(f"{self.channel_id}: no clients connected")
+
+        # Return DeliveryResult
+        return DeliveryResult(
+            channel_id=self.channel_id,
+            external_message_id=request.request_id,
+            delivered_at=datetime.now(),
+            success=successful > 0,
+            error_message=None if successful > 0 else "No clients connected",
+        )
+
+    async def receive(self):
+        """
+        Yield responses from clients as they arrive.
+
+        Yields:
+            ControlResponse objects
+        """
+        while True:
+            response = await self._response_queue.get()
+            logger.info(f"{self.channel_id}: received response for {response.request_id}")
+            yield response
+
+    async def cancel(self, request_id: str, reason: str) -> None:
+        """
+        Cancel a pending request.
+
+        Args:
+            request_id: Request to cancel
+            reason: Cancellation reason
+        """
+        logger.debug(f"{self.channel_id}: cancelling {request_id} ({reason})")
+
+        # Remove from pending
+        self._pending_requests.pop(request_id, None)
+
+        # Send cancellation to all clients
+        cancel_message = {"type": "control.cancelled", "request_id": request_id, "reason": reason}
+
+        for client_id, writer in list(self._clients.items()):
+            try:
+                await write_message(writer, cancel_message)
+            except Exception as e:
+                logger.error(f"{self.channel_id}: failed to send cancellation to {client_id}: {e}")
+
+    async def shutdown(self) -> None:
+        """Clean up and close server."""
+        logger.info(f"{self.channel_id}: shutting down")
+
+        # Close all client connections
+        for client_id, writer in list(self._clients.items()):
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception as e:
+                logger.error(f"{self.channel_id}: error closing client {client_id}: {e}")
+
+        self._clients.clear()
+
+        # Close server
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+
+        # Remove socket file
+        if os.path.exists(self.socket_path):
+            try:
+                os.unlink(self.socket_path)
+            except Exception as e:
+                logger.error(f"{self.channel_id}: failed to remove socket file: {e}")
+
+        self._initialized = False
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        """
+        Handle a connected client.
+
+        Args:
+            reader: asyncio StreamReader
+            writer: asyncio StreamWriter
+        """
+        client_id = str(uuid.uuid4())[:8]
+
+        logger.info(f"{self.channel_id}: client connected ({client_id})")
+
+        # Register client
+        self._clients[client_id] = writer
+
+        try:
+            # Send any pending requests to the new client
+            for request_id, request_data in self._pending_requests.items():
+                try:
+                    await write_message(writer, request_data)
+                except Exception as e:
+                    logger.error(
+                        f"{self.channel_id}: failed to send pending request to {client_id}: {e}"
+                    )
+
+            # Read messages from client
+            while True:
+                try:
+                    message = await read_message(reader)
+                except EOFError:
+                    break
+                except asyncio.IncompleteReadError:
+                    break
+
+                # Handle message
+                msg_type = message.get("type")
+
+                if msg_type == "control.response":
+                    # Parse response and queue it
+                    response = ControlResponse(
+                        request_id=message["request_id"],
+                        value=message["value"],
+                        responder_id=message.get("responder_id", client_id),
+                        responded_at=(
+                            datetime.fromisoformat(message["responded_at"])
+                            if message.get("responded_at")
+                            else datetime.now()
+                        ),
+                        timed_out=message.get("timed_out", False),
+                        channel_id=self.channel_id,
+                    )
+                    await self._response_queue.put(response)
+                    logger.info(f"{self.channel_id}: received response for {response.request_id}")
+
+                    # Remove from pending
+                    self._pending_requests.pop(response.request_id, None)
+
+                elif msg_type == "control.list":
+                    # Client requesting list of pending requests
+                    list_response = {
+                        "type": "control.list_response",
+                        "requests": list(self._pending_requests.values()),
+                    }
+                    await write_message(writer, list_response)
+
+                else:
+                    logger.warning(
+                        f"{self.channel_id}: unknown message type from {client_id}: {msg_type}"
+                    )
+
+        except Exception as e:
+            logger.error(f"{self.channel_id}: error handling client {client_id}: {e}")
+
+        finally:
+            # Clean up
+            self._clients.pop(client_id, None)
+            logger.info(f"{self.channel_id}: client disconnected ({client_id})")
+
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass