tactus 0.31.0__py3-none-any.whl → 0.34.1__py3-none-any.whl

tactus/adapters/channels/sse.py

@@ -0,0 +1,305 @@
+"""
+SSE Control Channel for IDE integration.
+
+Server-Sent Events channel that pushes HITL requests to connected IDEs
+and receives responses via HTTP POST callbacks.
+"""
+
+import asyncio
+import logging
+import queue
+from typing import Optional, Any
+from datetime import datetime, timezone
+
+from tactus.adapters.channels.base import InProcessChannel
+from tactus.protocols.control import (
+    ControlRequest,
+    ControlResponse,
+    ChannelCapabilities,
+    DeliveryResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SSEControlChannel(InProcessChannel):
+    """
+    Server-Sent Events channel for IDE HITL integration.
+
+    Reuses existing Flask SSE infrastructure. Sends hitl.request events
+    to connected IDE clients, receives responses via POST /hitl/response.
+
+    Architecture:
+    - send(): Pushes hitl.request event to SSE manager
+    - receive(): Yields responses from internal queue
+    - handle_ide_response(): Called by Flask POST endpoint to enqueue responses
+    """
+
+    def __init__(self, event_emitter: Optional[Any] = None):
+        """
+        Initialize SSE control channel.
+
+        Args:
+            event_emitter: Optional callable to emit SSE events.
+                          If None, uses a queue that can be consumed externally.
+        """
+        super().__init__()
+        self._event_emitter = event_emitter
+        # Use thread-safe queue.Queue for sync access from Flask SSE stream
+        self._event_queue: queue.Queue[dict] = queue.Queue()
+
+    @property
+    def channel_id(self) -> str:
+        return "sse"
+
+    @property
+    def capabilities(self) -> ChannelCapabilities:
+        return ChannelCapabilities(
+            supports_approval=True,
+            supports_input=True,
+            supports_review=True,
+            supports_escalation=True,
+            supports_select=True,
+            supports_upload=True,
+            supports_inputs=True,  # Batched inputs support
+            supports_interactive_buttons=True,
+            max_message_length=None,  # No length limit for IDE
+        )
+
+    async def initialize(self) -> None:
+        """Initialize SSE channel (no-op, Flask SSE already running)."""
+        logger.info(f"{self.channel_id}: initializing...")
+        # No auth or connection needed - Flask SSE already set up
+        logger.info(f"{self.channel_id}: ready")
+
+    async def send(self, request: ControlRequest) -> DeliveryResult:
+        """
+        Send HITL request as SSE event to connected IDEs.
+
+        Creates a hitl.request event with rich context and pushes to SSE stream.
+        """
+        logger.info(f"{self.channel_id}: sending notification for {request.request_id}")
+
+        try:
+            # Build SSE event payload
+            event = self._build_hitl_event(request)
+
+            # Emit event to SSE stream
+            if self._event_emitter:
+                await self._event_emitter(event)
+            else:
+                # Queue for external consumption if no emitter (thread-safe)
+                self._event_queue.put(event)
+
+            return DeliveryResult(
+                channel_id=self.channel_id,
+                external_message_id=request.request_id,
+                delivered_at=datetime.now(timezone.utc),
+                success=True,
+            )
+
+        except Exception as e:
+            logger.error(f"{self.channel_id}: failed to send notification: {e}")
+            return DeliveryResult(
+                channel_id=self.channel_id,
+                external_message_id=request.request_id,
+                delivered_at=datetime.now(timezone.utc),
+                success=False,
+                error_message=str(e),
+            )
+
+    def _build_hitl_event(self, request: ControlRequest) -> dict:
+        """
+        Build SSE event payload from ControlRequest.
+
+        Returns dict that will be serialized to JSON and sent as SSE event.
+        """
+        event = {
+            "event_type": "hitl.request",  # Frontend expects event_type, not type
+            "request_id": request.request_id,
+            # Identity
+            "procedure_id": request.procedure_id,
+            "procedure_name": request.procedure_name,
+            "invocation_id": request.invocation_id,
+            # Context
+            "subject": request.subject,
+            "started_at": request.started_at.isoformat() if request.started_at else None,
+            "input_summary": request.input_summary,
+            # The question
+            "request_type": request.request_type,
+            "message": request.message,
+            "default_value": request.default_value,
+            "timeout_seconds": request.timeout_seconds,
+            # Options
+            "options": (
+                [
+                    {
+                        "label": opt.label,
+                        "value": opt.value,
+                        "style": opt.style,
+                        "description": opt.description,
+                    }
+                    for opt in request.options
+                ]
+                if request.options
+                else []
+            ),
+            # For batched inputs requests
+            "items": (
+                [
+                    {
+                        "item_id": item.item_id,
+                        "label": item.label,
+                        "request_type": item.request_type,
+                        "message": item.message,
+                        "options": (
+                            [
+                                {
+                                    "label": opt.label,
+                                    "value": opt.value,
+                                    "style": opt.style,
+                                    "description": opt.description,
+                                }
+                                for opt in item.options
+                            ]
+                            if item.options
+                            else []
+                        ),
+                        "default_value": item.default_value,
+                        "required": item.required,
+                        "metadata": item.metadata,
+                    }
+                    for item in request.items
+                ]
+                if request.items
+                else []
+            ),
+            # Rich context for decision-making
+            "conversation": request.conversation,
+            "prior_interactions": request.prior_interactions,
+            # New context architecture (Phase 5)
+            "runtime_context": self._serialize_runtime_context(request.runtime_context),
+            "application_context": (
+                [
+                    {
+                        "name": link.name,
+                        "value": link.value,
+                        "url": link.url,
+                    }
+                    for link in request.application_context
+                ]
+                if request.application_context
+                else []
+            ),
+            # Additional metadata
+            "metadata": request.metadata,
+        }
+
+        return event
+
+    def _serialize_runtime_context(self, runtime_context) -> Optional[dict]:
+        """Serialize RuntimeContext to dict for SSE payload."""
+        if not runtime_context:
+            return None
+
+        return {
+            "source_line": runtime_context.source_line,
+            "source_file": runtime_context.source_file,
+            "checkpoint_position": runtime_context.checkpoint_position,
+            "procedure_name": runtime_context.procedure_name,
+            "invocation_id": runtime_context.invocation_id,
+            "started_at": (
+                runtime_context.started_at.isoformat() if runtime_context.started_at else None
+            ),
+            "elapsed_seconds": runtime_context.elapsed_seconds,
+            "backtrace": (
+                [
+                    {
+                        "checkpoint_type": bt.checkpoint_type,
+                        "line": bt.line,
+                        "function_name": bt.function_name,
+                        "duration_ms": bt.duration_ms,
+                    }
+                    for bt in runtime_context.backtrace
+                ]
+                if runtime_context.backtrace
+                else []
+            ),
+        }
+
+    def handle_ide_response(self, request_id: str, value: Any) -> None:
+        """
+        Handle response from IDE (called by Flask POST endpoint).
+
+        Bridges sync Flask handler to async channel protocol by pushing
+        to the internal response queue.
+
+        Args:
+            request_id: The request being responded to
+            value: The response value from the IDE
+        """
+        logger.info(f"{self.channel_id}: received response for {request_id}")
+
+        response = ControlResponse(
+            request_id=request_id,
+            value=value,
+            responded_at=datetime.now(timezone.utc),
+            timed_out=False,
+            channel_id=self.channel_id,
+        )
+
+        # Push to queue from sync context (Flask thread)
+        # Get the running event loop and schedule the put operation
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                # Schedule the coroutine in the running loop
+                asyncio.run_coroutine_threadsafe(self._response_queue.put(response), loop)
+            else:
+                # If no loop is running, use put_nowait (shouldn't happen)
+                self._response_queue.put_nowait(response)
+        except Exception as e:
+            logger.error(f"{self.channel_id}: failed to queue response for {request_id}: {e}")
+
+    def get_next_event(self, timeout: float = 0.001) -> Optional[dict]:
+        """
+        Get next SSE event from queue (for external consumption).
+
+        Used when no event_emitter is provided - allows Flask endpoint
+        to consume events from this channel.
+
+        Args:
+            timeout: Timeout in seconds
+
+        Returns:
+            Event dict or None if queue is empty
+        """
+        try:
+            event = self._event_queue.get(timeout=timeout)
+            return event
+        except queue.Empty:
+            return None
+
+    async def cancel(self, external_message_id: str, reason: str) -> None:
+        """
+        Cancel/dismiss HITL request in IDE.
+
+        Sends a hitl.cancel event to dismiss the prompt.
+        """
+        logger.debug(f"{self.channel_id}: cancelling {external_message_id}: {reason}")
+
+        cancel_event = {
+            "event_type": "hitl.cancel",  # Frontend expects event_type, not type
+            "request_id": external_message_id,
+            "reason": reason,
+        }
+
+        if self._event_emitter:
+            await self._event_emitter(cancel_event)
+        else:
+            self._event_queue.put(cancel_event)
+
+    async def shutdown(self) -> None:
+        """Shutdown SSE channel."""
+        logger.info(f"{self.channel_id}: shutting down")
+        self._shutdown_event.set()

tactus/adapters/cli_hitl.py

@@ -1,7 +1,11 @@
 """
 CLI HITL Handler for interactive human-in-the-loop interactions.
 
-Provides interactive prompts for approval, input, review, and escalation.
+This module provides backward compatibility with the existing HITLHandler protocol
+while the new control loop architecture is being developed.
+
+For new code, prefer using the ControlLoopHandler and CLIControlChannel classes
+from the control loop module.
 """
 
 import logging
@@ -22,6 +26,12 @@ class CLIHITLHandler:
     CLI-based HITL handler using rich prompts.
 
     Provides interactive command-line prompts for human-in-the-loop interactions.
+
+    Note: This class is maintained for backward compatibility. For new implementations,
+    consider using ControlLoopHandler with CLIControlChannel which supports:
+    - Multi-channel racing (first response wins)
+    - Interruptible prompts
+    - Namespace-based routing
     """
 
     def __init__(self, console: Optional[Console] = None):
@@ -66,6 +76,8 @@ class CLIHITLHandler:
             return self._handle_review(request)
         elif request.request_type == "escalation":
             return self._handle_escalation(request)
+        elif request.request_type == "inputs":
+            return self._handle_inputs(request)
         else:
             # Default: treat as input
             return self._handle_input(request)
@@ -172,6 +184,216 @@ class CLIHITLHandler:
         # Escalation doesn't need a specific value
         return HITLResponse(value=None, responded_at=datetime.now(timezone.utc), timed_out=False)
 
+    def _handle_inputs(self, request: HITLRequest) -> HITLResponse:
+        """Handle batched inputs request (multiple inputs in one interaction)."""
+        # Extract items from metadata
+        items = request.metadata.get("items", [])
+
+        if not items:
+            self.console.print("[red]Error: No items found in inputs request[/red]")
+            return HITLResponse(value={}, responded_at=datetime.now(timezone.utc), timed_out=False)
+
+        # Display summary
+        self.console.print(f"\n[bold cyan]Collecting {len(items)} inputs:[/bold cyan]")
+        for idx, item in enumerate(items, 1):
+            label = item.get("label", f"Item {idx}")
+            required = item.get("required", True)
+            req_marker = "*" if required else ""
+            self.console.print(f"  {idx}. [cyan]{label}[/cyan]{req_marker}")
+        self.console.print()
+
+        # Collect responses for each item
+        responses = {}
+
+        for idx, item in enumerate(items, 1):
+            item_id = item.get("item_id")
+            label = item.get("label", f"Item {idx}")
+            request_type = item.get("request_type", "input")
+            message = item.get("message", "")
+            required = item.get("required", True)
+            options = item.get("options", [])
+            default_value = item.get("default_value")
+            metadata = item.get("metadata", {})
+
+            # Display item panel
+            self.console.print(
+                Panel(
+                    message,
+                    title=f"[bold]{idx}/{len(items)}: {label}[/bold]",
+                    style="cyan" if required else "blue",
+                )
+            )
+
+            # Handle based on item type
+            if request_type == "approval":
+                default = default_value if default_value is not None else False
+                value = Confirm.ask("Approve?", default=default, console=self.console)
+
+            elif request_type == "select":
+                mode = metadata.get("mode", "single")
+
+                if mode == "multiple":
+                    # Multiple selection
+                    self.console.print(
+                        "\n[bold]Select multiple options (comma-separated numbers):[/bold]"
+                    )
+                    for i, option in enumerate(options, 1):
+                        label_text = (
+                            option.get("label", f"Option {i}")
+                            if isinstance(option, dict)
+                            else option
+                        )
+                        self.console.print(f"  {i}. [cyan]{label_text}[/cyan]")
+
+                    min_selections = metadata.get("min", 0)
+                    max_selections = metadata.get("max", len(options))
+
+                    while True:
+                        choice_str = Prompt.ask(
+                            "Select options (e.g., 1,3,4)", console=self.console
+                        )
+
+                        try:
+                            choices = [int(c.strip()) for c in choice_str.split(",")]
+                            if all(1 <= c <= len(options) for c in choices):
+                                if len(choices) < min_selections:
+                                    self.console.print(
+                                        f"[red]Select at least {min_selections} options[/red]"
+                                    )
+                                    continue
+                                if len(choices) > max_selections:
+                                    self.console.print(
+                                        f"[red]Select at most {max_selections} options[/red]"
+                                    )
+                                    continue
+
+                                # Get values for selected options
+                                selected_values = []
+                                for choice in choices:
+                                    opt = options[choice - 1]
+                                    if isinstance(opt, dict):
+                                        selected_values.append(opt.get("value", opt.get("label")))
+                                    else:
+                                        selected_values.append(opt)
+                                value = selected_values
+                                break
+                            else:
+                                self.console.print(
+                                    f"[red]Invalid choice. Enter 1-{len(options)}[/red]"
+                                )
+                        except ValueError:
+                            self.console.print(
+                                "[red]Invalid input. Enter comma-separated numbers[/red]"
+                            )
+                else:
+                    # Single selection
+                    self.console.print("\n[bold]Options:[/bold]")
+                    for i, option in enumerate(options, 1):
+                        if isinstance(option, dict):
+                            label_text = option.get("label", f"Option {i}")
+                            description = option.get("description", "")
+                            self.console.print(f"  {i}. [cyan]{label_text}[/cyan]")
+                            if description:
+                                self.console.print(f"     [dim]{description}[/dim]")
+                        else:
+                            self.console.print(f"  {i}. [cyan]{option}[/cyan]")
+
+                    while True:
+                        choice_str = Prompt.ask("Select option (number)", console=self.console)
+
+                        try:
+                            choice = int(choice_str)
+                            if 1 <= choice <= len(options):
+                                selected = options[choice - 1]
+                                if isinstance(selected, dict):
+                                    value = selected.get("value", selected.get("label"))
+                                else:
+                                    value = selected
+                                break
+                            else:
+                                self.console.print(
+                                    f"[red]Invalid choice. Enter 1-{len(options)}[/red]"
+                                )
+                        except ValueError:
+                            self.console.print("[red]Invalid input. Enter a number[/red]")
+
+            elif request_type == "review":
+                self.console.print("\n[bold]Review Options:[/bold]")
+                self.console.print("  1. [green]Approve[/green] - Accept as-is")
+                self.console.print("  2. [yellow]Edit[/yellow] - Provide changes")
+                self.console.print("  3. [red]Reject[/red] - Reject and request redo")
+
+                while True:
+                    choice = Prompt.ask(
+                        "Your decision",
+                        choices=["1", "2", "3", "approve", "edit", "reject"],
+                        default="1",
+                        console=self.console,
+                    )
+
+                    if choice in ["1", "approve"]:
+                        decision = "approved"
+                        feedback = None
+                        break
+                    elif choice in ["2", "edit"]:
+                        decision = "approved"
+                        feedback = Prompt.ask("What changes would you like?", console=self.console)
+                        break
+                    elif choice in ["3", "reject"]:
+                        decision = "rejected"
+                        feedback = Prompt.ask("Why are you rejecting?", console=self.console)
+                        break
+
+                value = {"decision": decision, "feedback": feedback}
+
+            else:
+                # Default: input type
+                placeholder = metadata.get("placeholder", "")
+                multiline = metadata.get("multiline", False)
+
+                if multiline:
+                    self.console.print("[dim](Enter text, press Ctrl+D when done)[/dim]")
+                    lines = []
+                    try:
+                        while True:
+                            line = Prompt.ask("", console=self.console, show_default=False)
+                            lines.append(line)
+                    except EOFError:
+                        value = "\n".join(lines)
+                else:
+                    prompt_text = "Enter value"
+                    if placeholder:
+                        prompt_text = f"{prompt_text} ({placeholder})"
+
+                    default_str = str(default_value) if default_value is not None else None
+                    value = Prompt.ask(prompt_text, default=default_str, console=self.console)
+
+            # Store response if required or if value was provided
+            if required or value:
+                responses[item_id] = value
+
+            self.console.print()  # Add spacing between items
+
+        # Display summary
+        self.console.print("[bold green]✓ All inputs collected[/bold green]")
+        self.console.print("\n[bold]Summary:[/bold]")
+        for item_id, value in responses.items():
+            # Find the label for this item_id
+            item_label = next(
+                (item.get("label", item_id) for item in items if item.get("item_id") == item_id),
+                item_id,
+            )
+            value_str = (
+                str(value) if not isinstance(value, list) else ", ".join(str(v) for v in value)
+            )
+            if len(value_str) > 60:
+                value_str = value_str[:57] + "..."
+            self.console.print(f"  [cyan]{item_label}:[/cyan] {value_str}")
+
+        return HITLResponse(
+            value=responses, responded_at=datetime.now(timezone.utc), timed_out=False
+        )
+
     def check_pending_response(self, procedure_id: str, message_id: str) -> Optional[HITLResponse]:
         """
         Check for pending response (not used in CLI mode).