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

tactus/__init__.py

@@ -5,7 +5,7 @@ Tactus provides a declarative workflow engine for AI agents with pluggable
 backends for storage, HITL, and chat recording.
 """
 
-__version__ = "0.33.0"
+__version__ = "0.34.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime

tactus/adapters/__init__.py

@@ -4,6 +4,23 @@ Tactus adapters - Built-in implementations of Tactus protocols.
 
 from tactus.adapters.memory import MemoryStorage
 from tactus.adapters.file_storage import FileStorage
+
+# Legacy HITL handler (maintained for backward compatibility)
 from tactus.adapters.cli_hitl import CLIHITLHandler
 
-__all__ = ["MemoryStorage", "FileStorage", "CLIHITLHandler"]
+# New control loop architecture
+from tactus.adapters.control_loop import ControlLoopHandler
+from tactus.adapters.channels import load_channels_from_config, load_default_channels
+from tactus.adapters.channels.cli import CLIControlChannel
+
+__all__ = [
+    "MemoryStorage",
+    "FileStorage",
+    # Legacy HITL
+    "CLIHITLHandler",
+    # New control loop
+    "ControlLoopHandler",
+    "CLIControlChannel",
+    "load_channels_from_config",
+    "load_default_channels",
+]

tactus/adapters/broker_log.py

@@ -1,52 +1,118 @@
 """
-Broker log handler for container event streaming over UDS.
+Broker log handler for container event streaming.
 
 Used inside the runtime container to forward structured log events to the
-host-side broker without requiring container networking.
+host-side broker for real-time streaming to the IDE frontend.
 """
 
 from __future__ import annotations
 
 import asyncio
+import logging
+import os
+import queue
 import threading
 from typing import Optional
 
-from tactus.broker.client import BrokerClient
 from tactus.protocols.models import LogEvent, CostEvent
 
+logger = logging.getLogger(__name__)
+
 
 class BrokerLogHandler:
     """
-    Log handler that forwards events to the broker via Unix domain socket.
+    Log handler that forwards events to the broker via background thread.
+
+    Uses a dedicated thread with its own event loop to ensure events are
+    sent in real-time, regardless of whether the main execution yields control.
+    This enables true streaming of agent responses to the frontend.
 
     The broker socket path is read from `TACTUS_BROKER_SOCKET`.
     """
 
-    def __init__(self, client: BrokerClient):
-        self._client = client
+    def __init__(self, socket_path: str):
+        self._socket_path = socket_path
         self.cost_events: list[CostEvent] = []
-        self._loop: Optional[asyncio.AbstractEventLoop] = None
-        self._loop_lock = threading.Lock()
 
-    def _get_or_create_loop(self) -> asyncio.AbstractEventLoop:
-        """Get the event loop, creating one if needed for cross-thread calls."""
-        with self._loop_lock:
-            if self._loop is None or self._loop.is_closed():
-                try:
-                    self._loop = asyncio.get_running_loop()
-                except RuntimeError:
-                    # No running loop - create a new one
-                    self._loop = asyncio.new_event_loop()
-            return self._loop
+        # Thread-safe queue for events to send
+        self._queue: queue.Queue = queue.Queue()
+
+        # Background worker thread
+        self._worker_thread: Optional[threading.Thread] = None
+        self._shutdown = threading.Event()
+        self._started = False
+        self._start_lock = threading.Lock()
+
+    @property
+    def supports_streaming(self) -> bool:
+        """Broker handler supports real-time streaming."""
+        return True
 
     @classmethod
     def from_environment(cls) -> Optional["BrokerLogHandler"]:
-        client = BrokerClient.from_environment()
-        if client is None:
+        """Create handler from TACTUS_BROKER_SOCKET environment variable."""
+        socket_path = os.environ.get("TACTUS_BROKER_SOCKET")
+        if not socket_path:
             return None
-        return cls(client)
+        return cls(socket_path)
+
+    def _ensure_worker_started(self) -> None:
+        """Start background worker thread if not already running."""
+        with self._start_lock:
+            if not self._started:
+                self._worker_thread = threading.Thread(
+                    target=self._worker,
+                    name="BrokerLogWorker",
+                    daemon=True,
+                )
+                self._worker_thread.start()
+                self._started = True
+                logger.debug("[BROKER_LOG] Background worker started")
+
+    def _worker(self) -> None:
+        """
+        Background thread that sends events to broker.
+
+        Runs in its own event loop to avoid blocking the main execution.
+        Creates a fresh BrokerClient connection for thread safety.
+        """
+        from tactus.broker.client import BrokerClient
+
+        # Create fresh client in this thread's event loop
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        client = BrokerClient(self._socket_path)
+
+        try:
+            while not self._shutdown.is_set():
+                try:
+                    # Wait for event with timeout to check shutdown flag
+                    event_dict = self._queue.get(timeout=0.05)
+
+                    # Send event to broker
+                    loop.run_until_complete(client.emit_event(event_dict))
+                    self._queue.task_done()
+
+                except queue.Empty:
+                    continue
+                except Exception as e:
+                    # Best effort - don't crash worker on individual failures
+                    logger.debug(f"[BROKER_LOG] Failed to emit event: {e}")
+                    try:
+                        self._queue.task_done()
+                    except ValueError:
+                        pass
+        finally:
+            loop.close()
+            logger.debug("[BROKER_LOG] Background worker stopped")
 
     def log(self, event: LogEvent) -> None:
+        """
+        Forward an event to the broker.
+
+        Events are queued and sent by a background thread, enabling
+        real-time streaming without blocking procedure execution.
+        """
         # Track cost events for aggregation (mirrors IDELogHandler behavior)
         if isinstance(event, CostEvent):
             self.cost_events.append(event)
@@ -60,17 +126,44 @@ class BrokerLogHandler:
             iso_string += "Z"
         event_dict["timestamp"] = iso_string
 
-        # Best-effort forwarding; never crash the procedure due to streaming.
+        # Ensure worker is running
+        self._ensure_worker_started()
+
+        # Queue event for background sending (non-blocking)
         try:
-            # Try to get the running loop first
-            try:
-                loop = asyncio.get_running_loop()
-                # We're in an async context - schedule and don't wait
-                loop.create_task(self._client.emit_event(event_dict))
-            except RuntimeError:
-                # No running loop - we're being called from a sync thread.
-                # Use asyncio.run() which creates a new event loop for this call.
-                asyncio.run(self._client.emit_event(event_dict))
-        except Exception:
-            # Swallow errors; container remains networkless and secretless even if streaming fails.
-            pass
+            self._queue.put_nowait(event_dict)
+        except queue.Full:
+            # Drop event if queue is full (shouldn't happen with unlimited queue)
+            logger.debug("[BROKER_LOG] Queue full, dropping event")
+
+    async def flush(self) -> None:
+        """
+        Wait for all queued events to be sent.
+
+        Call this before procedure completion to ensure all events
+        are delivered to the broker before the container exits.
+        """
+        if not self._started:
+            return
+
+        # Wait for queue to drain
+        max_wait = 5.0  # Maximum wait time in seconds
+        poll_interval = 0.05
+        elapsed = 0.0
+
+        while not self._queue.empty() and elapsed < max_wait:
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+
+        if not self._queue.empty():
+            remaining = self._queue.qsize()
+            logger.warning(f"[BROKER_LOG] Flush timeout with {remaining} events remaining")
+
+        # Signal worker to shutdown
+        self._shutdown.set()
+
+        # Wait for worker thread to finish
+        if self._worker_thread and self._worker_thread.is_alive():
+            self._worker_thread.join(timeout=1.0)
+            if self._worker_thread.is_alive():
+                logger.warning("[BROKER_LOG] Worker thread did not stop cleanly")

tactus/adapters/channels/__init__.py

@@ -0,0 +1,153 @@
+"""
+Control channel implementations for omnichannel control loop.
+
+This package contains control channel plugins:
+- CLI: Command-line interface for terminal control (host app pattern)
+- IDE/SSE: Server-Sent Events for VSCode extension (Phase 2)
+- Tactus Cloud: WebSocket API for companion app (Phase 5)
+- Additional channels as needed: Slack, Teams, Email, etc.
+
+The control loop uses a publish-subscribe pattern with namespace-based routing:
+- Publishers (Tactus runtimes) emit control requests to namespaces
+- Subscribers (controllers) subscribe to namespace patterns
+- Subscribers can be observers (read-only) or responders (can provide input)
+"""
+
+from typing import List, Dict, Any, Optional
+import logging
+import sys
+
+from tactus.protocols.control import ControlChannel, ControlLoopConfig
+
+logger = logging.getLogger(__name__)
+
+
+# Channel registry for lazy loading
+_CHANNEL_LOADERS = {
+    "cli": "tactus.adapters.channels.cli:CLIControlChannel",
+    "ipc": "tactus.adapters.channels.ipc:IPCControlChannel",
+    # "ide": "tactus.adapters.channels.ide_sse:SSEControlChannel",  # Phase 2
+    # "tactus_cloud": "tactus.adapters.channels.tactus_cloud:TactusCloudChannel",  # Phase 5
+}
+
+
+def load_channel(channel_id: str, config: Dict[str, Any]) -> Optional[ControlChannel]:
+    """
+    Load a control channel by ID.
+
+    Args:
+        channel_id: Channel identifier (e.g., 'cli', 'ide', 'tactus_cloud')
+        config: Channel configuration dict
+
+    Returns:
+        ControlChannel instance or None if loading fails
+    """
+    if channel_id not in _CHANNEL_LOADERS:
+        logger.warning(f"Unknown or not yet implemented channel: {channel_id}")
+        return None
+
+    module_path = _CHANNEL_LOADERS[channel_id]
+    module_name, class_name = module_path.rsplit(":", 1)
+
+    try:
+        import importlib
+
+        module = importlib.import_module(module_name)
+        channel_class = getattr(module, class_name)
+        return channel_class(**config)
+    except ImportError as e:
+        logger.warning(
+            f"Failed to load {channel_id} channel. "
+            f"Ensure dependencies are installed. "
+            f"Error: {e}"
+        )
+        return None
+    except Exception as e:
+        logger.exception(f"Failed to initialize {channel_id} channel: {e}")
+        return None
+
+
+def load_channels_from_config(config: Optional[ControlLoopConfig] = None) -> List[ControlChannel]:
+    """
+    Load control channels based on configuration and context.
+
+    By default:
+    - CLI channel is enabled if stdin is a tty (interactive terminal)
+    - Other channels are loaded based on configuration
+
+    Args:
+        config: Optional control loop configuration
+
+    Returns:
+        List of enabled ControlChannel instances
+    """
+    channels: List[ControlChannel] = []
+
+    if config is None:
+        config = ControlLoopConfig()
+
+    # Process each configured channel
+    for channel_id, channel_config in config.channels.items():
+        enabled = channel_config.get("enabled", False)
+
+        # Special handling for CLI with auto-detection
+        if channel_id == "cli":
+            if enabled == "auto" or enabled is None:
+                enabled = sys.stdin.isatty()
+            elif isinstance(enabled, str):
+                enabled = enabled.lower() == "true"
+
+        if not enabled:
+            continue
+
+        # Remove 'enabled' from config before passing to constructor
+        init_config = {k: v for k, v in channel_config.items() if k != "enabled"}
+        channel = load_channel(channel_id, init_config)
+        if channel:
+            channels.append(channel)
+            logger.info(f"Loaded control channel: {channel_id}")
+
+    # If no channels configured, use defaults
+    if not config.channels:
+        channels = load_default_channels()
+
+    return channels
+
+
+def load_default_channels(procedure_id: Optional[str] = None) -> List[ControlChannel]:
+    """
+    Load default control channels based on context.
+
+    By default:
+    - CLI channel is enabled if stdin is a tty (interactive terminal)
+    - IPC channel is always enabled (allows control CLI to connect)
+
+    Args:
+        procedure_id: Optional procedure ID for IPC socket path
+
+    Returns:
+        List of enabled ControlChannel instances
+    """
+    channels: List[ControlChannel] = []
+
+    # CLI channel - auto-detect based on tty
+    if sys.stdin.isatty():
+        from tactus.adapters.channels.cli import CLIControlChannel
+
+        channels.append(CLIControlChannel())
+        logger.info("Loaded CLI control channel (auto-detected tty)")
+
+    # IPC channel - always enabled for control CLI connectivity
+    from tactus.adapters.channels.ipc import IPCControlChannel
+
+    channels.append(IPCControlChannel(procedure_id=procedure_id))
+    logger.info("Loaded IPC control channel")
+
+    return channels
+
+
+__all__ = [
+    "load_channel",
+    "load_channels_from_config",
+    "load_default_channels",
+]

tactus/adapters/channels/base.py

@@ -0,0 +1,174 @@
+"""
+Base classes for control channel implementations.
+
+Provides InProcessChannel for channels that work with asyncio in-process.
+A DaemonChannel base class may be added later if needed for channels
+requiring separate processes (e.g., Discord WebSocket gateway).
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import AsyncIterator
+
+from tactus.protocols.control import (
+    ControlRequest,
+    ControlResponse,
+    ChannelCapabilities,
+    DeliveryResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class InProcessChannel(ABC):
+    """
+    Base class for control channels that run in-process with asyncio.
+
+    Suitable for:
+    - Host app channels (CLI, IDE server, Jupyter)
+    - HTTP webhooks (Slack, Teams)
+    - Queue polling (SQS, Redis)
+    - Email (SMTP send)
+    - WebSocket clients (Tactus Cloud)
+
+    These channels coexist with the asyncio event loop and don't need
+    separate processes.
+
+    Subclasses must implement:
+    - channel_id property
+    - capabilities property
+    - send() method
+
+    Default implementations provided for:
+    - initialize() - no-op
+    - receive() - yields from internal response queue
+    - cancel() - no-op
+    - shutdown() - no-op
+
+    The response queue pattern:
+    - External handlers (webhooks, stdin readers, etc.) call push_response()
+    - receive() yields from the queue
+    - This bridges sync/async boundaries cleanly
+    """
+
+    def __init__(self):
+        """Initialize the channel with an internal response queue."""
+        self._response_queue: asyncio.Queue[ControlResponse] = asyncio.Queue()
+        self._shutdown_event = asyncio.Event()
+
+    @property
+    @abstractmethod
+    def channel_id(self) -> str:
+        """Unique identifier for this channel."""
+        ...
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> ChannelCapabilities:
+        """Return channel capabilities."""
+        ...
+
+    async def initialize(self) -> None:
+        """
+        Initialize the channel.
+
+        Default: no-op. Override for auth handshakes, connections, etc.
+        """
+        logger.info(f"{self.channel_id}: initializing...")
+        logger.info(f"{self.channel_id}: ready")
+
+    @abstractmethod
+    async def send(self, request: ControlRequest) -> DeliveryResult:
+        """
+        Send a control request to this channel.
+
+        Subclass must implement channel-specific send logic.
+
+        Args:
+            request: ControlRequest with full context
+
+        Returns:
+            DeliveryResult with delivery status
+        """
+        ...
+
+    async def receive(self) -> AsyncIterator[ControlResponse]:
+        """
+        Yield responses as they arrive from the internal queue.
+
+        External handlers (webhooks, stdin readers, etc.) call push_response()
+        to add responses to the queue.
+
+        Override for polling-based channels that need custom receive logic.
+
+        Yields:
+            ControlResponse as they are received
+        """
+        while not self._shutdown_event.is_set():
+            try:
+                # Use wait_for with timeout to check shutdown periodically
+                response = await asyncio.wait_for(
+                    self._response_queue.get(),
+                    timeout=0.5,
+                )
+                logger.info(f"{self.channel_id}: received response for {response.request_id}")
+                yield response
+            except asyncio.TimeoutError:
+                continue
+            except asyncio.CancelledError:
+                break
+
+    async def cancel(self, external_message_id: str, reason: str) -> None:
+        """
+        Cancel or update a request when resolved via another channel.
+
+        Default: no-op. Override for channels that support message updates
+        (e.g., editing Slack messages, updating UI).
+
+        Args:
+            external_message_id: Channel-specific message ID
+            reason: Reason for cancellation
+        """
+        logger.debug(f"{self.channel_id}: cancelling {external_message_id}: {reason}")
+
+    async def shutdown(self) -> None:
+        """
+        Clean shutdown of the channel.
+
+        Default: sets shutdown event to stop receive loop.
+        Override for additional cleanup (close connections, etc.).
+        """
+        logger.info(f"{self.channel_id}: shutting down")
+        self._shutdown_event.set()
+
+    def push_response(self, response: ControlResponse) -> None:
+        """
+        Push a response to the internal queue.
+
+        Called by external handlers (webhooks, stdin readers, etc.) when
+        a response is received. This bridges sync/async boundaries.
+
+        Thread-safe: can be called from non-async contexts.
+
+        Args:
+            response: ControlResponse to add to queue
+        """
+        try:
+            self._response_queue.put_nowait(response)
+        except Exception as e:
+            logger.error(f"{self.channel_id}: failed to queue response: {e}")
+
+    def push_response_threadsafe(
+        self, response: ControlResponse, loop: asyncio.AbstractEventLoop
+    ) -> None:
+        """
+        Push a response to the queue from another thread.
+
+        Use this when calling from a background thread (e.g., stdin reader).
+
+        Args:
+            response: ControlResponse to add to queue
+            loop: The event loop to use for thread-safe call
+        """
+        loop.call_soon_threadsafe(self._response_queue.put_nowait, response)