tactus 0.31.0__py3-none-any.whl

tactus/__init__.py

@@ -0,0 +1,49 @@
+"""
+Tactus: Lua-based DSL for agentic workflows.
+
+Tactus provides a declarative workflow engine for AI agents with pluggable
+backends for storage, HITL, and chat recording.
+"""
+
+__version__ = "0.31.0"
+
+# Core exports
+from tactus.core.runtime import TactusRuntime
+from tactus.core.exceptions import (
+    TactusRuntimeError,
+    ProcedureWaitingForHuman,
+    ProcedureConfigError,
+    LuaSandboxError,
+    OutputValidationError,
+)
+
+# Protocol exports
+from tactus.protocols.storage import StorageBackend, ProcedureMetadata
+from tactus.protocols.models import CheckpointEntry
+from tactus.protocols.hitl import HITLHandler, HITLRequest, HITLResponse
+from tactus.protocols.chat_recorder import ChatRecorder, ChatMessage
+from tactus.protocols.config import TactusConfig, ProcedureConfig
+
+__all__ = [
+    # Version
+    "__version__",
+    # Runtime
+    "TactusRuntime",
+    # Exceptions
+    "TactusRuntimeError",
+    "ProcedureWaitingForHuman",
+    "ProcedureConfigError",
+    "LuaSandboxError",
+    "OutputValidationError",
+    # Protocols
+    "StorageBackend",
+    "ProcedureMetadata",
+    "CheckpointEntry",
+    "HITLHandler",
+    "HITLRequest",
+    "HITLResponse",
+    "ChatRecorder",
+    "ChatMessage",
+    "TactusConfig",
+    "ProcedureConfig",
+]

tactus/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""
+Tactus adapters - Built-in implementations of Tactus protocols.
+"""
+
+from tactus.adapters.memory import MemoryStorage
+from tactus.adapters.file_storage import FileStorage
+from tactus.adapters.cli_hitl import CLIHITLHandler
+
+__all__ = ["MemoryStorage", "FileStorage", "CLIHITLHandler"]

tactus/adapters/broker_log.py

@@ -0,0 +1,76 @@
+"""
+Broker log handler for container event streaming over UDS.
+
+Used inside the runtime container to forward structured log events to the
+host-side broker without requiring container networking.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Optional
+
+from tactus.broker.client import BrokerClient
+from tactus.protocols.models import LogEvent, CostEvent
+
+
+class BrokerLogHandler:
+    """
+    Log handler that forwards events to the broker via Unix domain socket.
+
+    The broker socket path is read from `TACTUS_BROKER_SOCKET`.
+    """
+
+    def __init__(self, client: BrokerClient):
+        self._client = client
+        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
+
+    @classmethod
+    def from_environment(cls) -> Optional["BrokerLogHandler"]:
+        client = BrokerClient.from_environment()
+        if client is None:
+            return None
+        return cls(client)
+
+    def log(self, event: LogEvent) -> None:
+        # Track cost events for aggregation (mirrors IDELogHandler behavior)
+        if isinstance(event, CostEvent):
+            self.cost_events.append(event)
+
+        # Serialize to JSON-friendly dict
+        event_dict = event.model_dump(mode="json")
+
+        # Normalize timestamp formatting for downstream consumers.
+        iso_string = event.timestamp.isoformat()
+        if not (iso_string.endswith("Z") or "+" in iso_string or iso_string.count("-") > 2):
+            iso_string += "Z"
+        event_dict["timestamp"] = iso_string
+
+        # Best-effort forwarding; never crash the procedure due to streaming.
+        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

tactus/adapters/cli_hitl.py

@@ -0,0 +1,189 @@
+"""
+CLI HITL Handler for interactive human-in-the-loop interactions.
+
+Provides interactive prompts for approval, input, review, and escalation.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+
+from rich.console import Console
+from rich.prompt import Prompt, Confirm
+from rich.panel import Panel
+
+from tactus.protocols.models import HITLRequest, HITLResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CLIHITLHandler:
+    """
+    CLI-based HITL handler using rich prompts.
+
+    Provides interactive command-line prompts for human-in-the-loop interactions.
+    """
+
+    def __init__(self, console: Optional[Console] = None):
+        """
+        Initialize CLI HITL handler.
+
+        Args:
+            console: Rich Console instance (creates new one if not provided)
+        """
+        self.console = console or Console()
+        logger.debug("CLIHITLHandler initialized")
+
+    def request_interaction(self, procedure_id: str, request: HITLRequest) -> HITLResponse:
+        """
+        Request human interaction via CLI prompt.
+
+        Args:
+            procedure_id: Procedure ID
+            request: HITLRequest with interaction details
+
+        Returns:
+            HITLResponse with user's response
+        """
+        logger.debug(f"HITL request: {request.request_type} - {request.message}")
+
+        # Display the request in a panel
+        self.console.print()
+        self.console.print(
+            Panel(
+                request.message,
+                title=f"[bold]{request.request_type.upper()}[/bold]",
+                style="yellow",
+            )
+        )
+
+        # Handle based on request type
+        if request.request_type == "approval":
+            return self._handle_approval(request)
+        elif request.request_type == "input":
+            return self._handle_input(request)
+        elif request.request_type == "review":
+            return self._handle_review(request)
+        elif request.request_type == "escalation":
+            return self._handle_escalation(request)
+        else:
+            # Default: treat as input
+            return self._handle_input(request)
+
+    def _handle_approval(self, request: HITLRequest) -> HITLResponse:
+        """Handle approval request."""
+        default = request.default_value if request.default_value is not None else False
+
+        # Use rich Confirm for yes/no
+        approved = Confirm.ask("Approve?", default=default, console=self.console)
+
+        return HITLResponse(
+            value=approved, responded_at=datetime.now(timezone.utc), timed_out=False
+        )
+
+    def _handle_input(self, request: HITLRequest) -> HITLResponse:
+        """Handle input request."""
+        default = str(request.default_value) if request.default_value is not None else None
+
+        # Check if there are options
+        if request.options:
+            # Display options
+            self.console.print("\n[bold]Options:[/bold]")
+            for i, option in enumerate(request.options, 1):
+                label = option.get("label", f"Option {i}")
+                description = option.get("description", "")
+                self.console.print(f"  {i}. [cyan]{label}[/cyan]")
+                if description:
+                    self.console.print(f"     [dim]{description}[/dim]")
+
+            # Get choice
+            while True:
+                choice_str = Prompt.ask(
+                    "Select option (number)", default=default, console=self.console
+                )
+
+                try:
+                    choice = int(choice_str)
+                    if 1 <= choice <= len(request.options):
+                        selected = request.options[choice - 1]
+                        value = selected.get("value", selected.get("label"))
+                        break
+                    else:
+                        self.console.print(
+                            f"[red]Invalid choice. Enter 1-{len(request.options)}[/red]"
+                        )
+                except ValueError:
+                    self.console.print("[red]Invalid input. Enter a number[/red]")
+
+        else:
+            # Free-form input
+            value = Prompt.ask("Enter value", default=default, console=self.console)
+
+        return HITLResponse(value=value, responded_at=datetime.now(timezone.utc), timed_out=False)
+
+    def _handle_review(self, request: HITLRequest) -> HITLResponse:
+        """Handle review request."""
+        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
+                edited_artifact = None
+                break
+            elif choice in ["2", "edit"]:
+                decision = "approved"
+                feedback = Prompt.ask("What changes would you like?", console=self.console)
+                # In CLI, we can't easily edit artifacts, so just provide feedback
+                edited_artifact = None
+                break
+            elif choice in ["3", "reject"]:
+                decision = "rejected"
+                feedback = Prompt.ask("Why are you rejecting?", console=self.console)
+                edited_artifact = None
+                break
+
+        value = {"decision": decision, "feedback": feedback, "edited_artifact": edited_artifact}
+
+        return HITLResponse(value=value, responded_at=datetime.now(timezone.utc), timed_out=False)
+
+    def _handle_escalation(self, request: HITLRequest) -> HITLResponse:
+        """Handle escalation request."""
+        self.console.print("\n[yellow bold]⚠ This issue requires escalation[/yellow bold]")
+
+        # Wait for acknowledgment
+        Confirm.ask(
+            "Press Enter to acknowledge and continue",
+            default=True,
+            show_default=False,
+            console=self.console,
+        )
+
+        # Escalation doesn't need a specific value
+        return HITLResponse(value=None, 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).
+
+        In CLI mode, interactions are synchronous, so this always returns None.
+        """
+        return None
+
+    def cancel_pending_request(self, procedure_id: str, message_id: str) -> None:
+        """
+        Cancel pending request (not used in CLI mode).
+
+        In CLI mode, interactions are synchronous, so this is a no-op.
+        """
+        pass

tactus/adapters/cli_log.py

@@ -0,0 +1,223 @@
+"""
+CLI Log Handler for Rich-formatted logging.
+
+Renders log events using Rich console for beautiful CLI output.
+"""
+
+import logging
+from typing import Optional
+from rich.console import Console
+
+from tactus.protocols.models import LogEvent, CostEvent
+
+logger = logging.getLogger(__name__)
+
+
+class CLILogHandler:
+    """
+    CLI log handler using Rich formatting.
+
+    Receives structured log events and renders them with Rich
+    for beautiful console output.
+    """
+
+    def __init__(self, console: Optional[Console] = None):
+        """
+        Initialize CLI log handler.
+
+        Args:
+            console: Rich Console instance (creates new one if not provided)
+        """
+        self.console = console or Console()
+        self.cost_events = []  # Track cost events for aggregation
+        logger.debug("CLILogHandler initialized")
+
+    def log(self, event: LogEvent) -> None:
+        """
+        Render log event with Rich formatting.
+
+        Args:
+            event: Structured log event
+        """
+        # Handle stream chunks specially
+        from tactus.protocols.models import AgentStreamChunkEvent
+
+        if isinstance(event, AgentStreamChunkEvent):
+            self._display_stream_chunk(event)
+            return
+
+        # Handle cost events specially
+        if isinstance(event, CostEvent):
+            self._display_cost_event(event)
+            return
+
+        # Handle agent turn events
+        from tactus.protocols.models import AgentTurnEvent
+
+        if isinstance(event, AgentTurnEvent):
+            self._display_agent_turn_event(event)
+            return
+
+        # Handle tool call events
+        from tactus.protocols.models import ToolCallEvent
+
+        if isinstance(event, ToolCallEvent):
+            self._display_tool_call_event(event)
+            return
+
+        # Handle checkpoint created events
+        from tactus.protocols.models import CheckpointCreatedEvent
+
+        if isinstance(event, CheckpointCreatedEvent):
+            self._display_checkpoint_event(event)
+            return
+
+        # Handle ExecutionSummaryEvent specially
+        if event.event_type == "execution_summary":
+            self._display_execution_summary(event)
+            return
+
+        # Use Rich to format nicely for other events
+        if hasattr(event, "context") and event.context:
+            # Log with context formatted as part of the message
+            import json
+
+            context_str = json.dumps(event.context, indent=2)
+            self.console.log(f"{event.message}\n{context_str}")
+        else:
+            # Simple log message
+            self.console.log(event.message)
+
+    def _display_stream_chunk(self, event) -> None:
+        """Display streaming text chunk in real-time."""
+        # Print chunk without newline so text flows naturally
+        # Use markup=False to avoid interpreting Rich markup in the text
+        self.console.print(event.chunk_text, end="", markup=False)
+
+    def _display_agent_turn_event(self, event) -> None:
+        """Display agent turn start/complete event."""
+
+        if event.stage == "started":
+            self.console.print(
+                f"[blue]→ Agent[/blue] [bold]{event.agent_name}[/bold]: [blue]Waiting for response...[/blue]"
+            )
+        elif event.stage == "completed":
+            # Add newline after streaming completes to separate from next output
+            self.console.print()  # Newline after streamed text
+            duration_str = f"{event.duration_ms:.0f}ms" if event.duration_ms else ""
+            self.console.print(
+                f"[green]✓ Agent[/green] [bold]{event.agent_name}[/bold]: [green]Completed[/green] {duration_str}"
+            )
+
+    def _display_tool_call_event(self, event) -> None:
+        """Display tool call event."""
+        import json
+
+        # Format arguments compactly if they're simple
+        args_str = ""
+        if event.tool_args:
+            # For simple args, show inline
+            if len(event.tool_args) == 1 and len(str(event.tool_args)) < 60:
+                args_str = f" {json.dumps(event.tool_args, default=str)}"
+            else:
+                # For complex args, show on next line
+                args_str = f"\n  Args: {json.dumps(event.tool_args, indent=2, default=str)}"
+
+        # Format result if available
+        result_str = ""
+        if event.tool_result is not None:
+            result_value = str(event.tool_result)
+            if len(result_value) < 60:
+                result_str = f"\n  Result: {result_value}"
+            else:
+                # Truncate long results
+                result_str = f"\n  Result: {result_value[:57]}..."
+
+        duration_str = f" ({event.duration_ms:.0f}ms)" if event.duration_ms else ""
+
+        self.console.print(
+            f"[cyan]→ Tool[/cyan] [bold]{event.tool_name}[/bold]{args_str}{result_str}{duration_str}"
+        )
+
+    def _display_checkpoint_event(self, event) -> None:
+        """Display checkpoint created event."""
+        # Format checkpoint type (e.g., "agent_turn" -> "Agent Turn")
+        type_display = event.checkpoint_type.replace("_", " ").title()
+
+        # Format duration if available
+        duration_str = f" ({event.duration_ms:.0f}ms)" if event.duration_ms else ""
+
+        # Format source location if available
+        location_str = ""
+        if event.source_location:
+            location_str = (
+                f"\n  Location: {event.source_location.file}:{event.source_location.line}"
+            )
+
+        self.console.print(
+            f"[yellow]• Checkpoint[/yellow] [bold]{event.checkpoint_position}[/bold]: {type_display}{duration_str}{location_str}"
+        )
+
+    def _display_cost_event(self, event: CostEvent) -> None:
+        """Display cost event with comprehensive metrics."""
+        # Track cost event for aggregation
+        self.cost_events.append(event)
+
+        # Primary metrics - always show
+        self.console.print(
+            f"[green]$ Cost[/green] [bold]{event.agent_name}[/bold]: "
+            f"[green bold]${event.total_cost:.6f}[/green bold] "
+            f"({event.total_tokens:,} tokens, {event.model}"
+            f"{f', {event.duration_ms:.0f}ms' if event.duration_ms else ''})"
+        )
+
+        # Show retry warning if applicable
+        if event.retry_count > 0:
+            self.console.print(
+                f"  [yellow]⚠ Retried {event.retry_count} time(s) due to validation[/yellow]"
+            )
+
+        # Show cache hit if applicable
+        if event.cache_hit and event.cache_tokens:
+            self.console.print(
+                f"  [green]✓ Cache hit: {event.cache_tokens:,} tokens"
+                f"{f' (saved ${event.cache_cost:.6f})' if event.cache_cost else ''}[/green]"
+            )
+
+    def _display_execution_summary(self, event) -> None:
+        """Display execution summary with cost breakdown."""
+        self.console.print(
+            f"\n[green bold]✓ Procedure completed[/green bold]: "
+            f"{event.iterations} iterations, {len(event.tools_used)} tools used"
+        )
+
+        # Display cost summary if costs were incurred
+        if hasattr(event, "total_cost") and event.total_cost > 0:
+            self.console.print("\n[green bold]$ Cost Summary[/green bold]")
+            self.console.print(f"  Total Cost: [green bold]${event.total_cost:.6f}[/green bold]")
+            self.console.print(f"  Total Tokens: {event.total_tokens:,}")
+
+            if hasattr(event, "cost_breakdown") and event.cost_breakdown:
+                self.console.print("\n  [bold]Per-call breakdown:[/bold]")
+                for cost in event.cost_breakdown:
+                    self.console.print(
+                        f"    {cost.agent_name}: ${cost.total_cost:.6f} "
+                        f"({cost.total_tokens:,} tokens, {cost.duration_ms:.0f}ms)"
+                    )
+
+        # Display checkpoint summary if checkpoints were created
+        if hasattr(event, "checkpoint_count") and event.checkpoint_count > 0:
+            self.console.print("\n[yellow bold]• Checkpoint Summary[/yellow bold]")
+            self.console.print(f"  Total Checkpoints: {event.checkpoint_count}")
+
+            if hasattr(event, "checkpoint_types") and event.checkpoint_types:
+                self.console.print("  Types:")
+                for checkpoint_type, count in sorted(event.checkpoint_types.items()):
+                    type_display = checkpoint_type.replace("_", " ").title()
+                    self.console.print(f"    {type_display}: {count}")
+
+            if hasattr(event, "checkpoint_duration_ms") and event.checkpoint_duration_ms:
+                avg_duration = event.checkpoint_duration_ms / event.checkpoint_count
+                total_seconds = event.checkpoint_duration_ms / 1000
+                self.console.print(f"  Average Duration: {avg_duration:.0f}ms")
+                self.console.print(f"  Total Duration: {total_seconds:.1f}s")

tactus/adapters/cost_collector_log.py

@@ -0,0 +1,56 @@
+"""
+Cost-only log handler for headless/sandbox runs.
+
+Collects CostEvent instances so the runtime can report total_cost/total_tokens,
+without enabling streaming UI behavior.
+"""
+
+from __future__ import annotations
+
+import logging
+import json
+from typing import List
+
+from tactus.protocols.models import CostEvent, LogEvent
+
+logger = logging.getLogger(__name__)
+
+
+class CostCollectorLogHandler:
+    """
+    Minimal LogHandler for sandbox runs.
+
+    This is useful in environments like Docker sandboxes where stdout is reserved
+    for protocol output, but we still want:
+    - accurate cost accounting (CostEvent)
+    - basic procedure logging (LogEvent) via stderr/Python logging
+    """
+
+    supports_streaming = False
+
+    def __init__(self):
+        self.cost_events: List[CostEvent] = []
+        logger.debug("CostCollectorLogHandler initialized")
+
+    def log(self, event: LogEvent) -> None:
+        if isinstance(event, CostEvent):
+            self.cost_events.append(event)
+            return
+
+        # Preserve useful procedure logs even when no IDE callback is present.
+        if isinstance(event, LogEvent):
+            event_logger = logging.getLogger(event.logger_name or "procedure")
+
+            msg = event.message
+            if event.context:
+                msg = f"{msg}\nContext: {json.dumps(event.context, indent=2, default=str)}"
+
+            level = (event.level or "INFO").upper()
+            if level == "DEBUG":
+                event_logger.debug(msg)
+            elif level in ("WARN", "WARNING"):
+                event_logger.warning(msg)
+            elif level == "ERROR":
+                event_logger.error(msg)
+            else:
+                event_logger.info(msg)