tactus 0.31.2__py3-none-any.whl

tactus/adapters/file_storage.py

@@ -0,0 +1,367 @@
+"""
+File-based storage backend for Tactus.
+
+Stores procedure metadata and execution log as JSON files on disk.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Optional, Dict, List
+from datetime import datetime
+
+from tactus.protocols.models import (
+    ProcedureMetadata,
+    CheckpointEntry,
+    ExecutionRun,
+    Breakpoint,
+    SourceLocation,
+)
+
+
+class FileStorage:
+    """
+    File-based storage backend.
+
+    Stores each procedure's metadata in a separate JSON file:
+    {storage_dir}/{procedure_id}.json
+    """
+
+    def __init__(self, storage_dir: str = "~/.tactus/storage"):
+        """
+        Initialize file storage.
+
+        Args:
+            storage_dir: Directory to store procedure files
+        """
+        self.storage_dir = Path(storage_dir).expanduser()
+
+        # Try to create directories, but don't fail if we can't
+        # This allows read-only testing and defers errors to write operations
+        try:
+            self.storage_dir.mkdir(parents=True, exist_ok=True)
+        except (PermissionError, OSError):
+            pass  # Defer error to actual write operations
+
+        # Create subdirectories for tracing
+        self.traces_dir = self.storage_dir / "traces"
+        self.runs_dir = self.traces_dir / "runs"
+        self.breakpoints_dir = self.traces_dir / "breakpoints"
+        self.index_file = self.traces_dir / "index.json"
+
+        # Try to create subdirectories, but defer errors to write operations
+        try:
+            self.traces_dir.mkdir(parents=True, exist_ok=True)
+            self.runs_dir.mkdir(parents=True, exist_ok=True)
+            self.breakpoints_dir.mkdir(parents=True, exist_ok=True)
+        except (PermissionError, OSError):
+            pass  # Defer error to actual write operations
+
+    def _get_file_path(self, procedure_id: str) -> Path:
+        """Get the file path for a procedure."""
+        return self.storage_dir / f"{procedure_id}.json"
+
+    def _read_file(self, procedure_id: str) -> dict:
+        """Read procedure file, return empty dict if not found."""
+        file_path = self._get_file_path(procedure_id)
+        if not file_path.exists():
+            return {}
+
+        try:
+            with open(file_path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError) as e:
+            raise RuntimeError(f"Failed to read procedure file {file_path}: {e}")
+
+    def _write_file(self, procedure_id: str, data: dict) -> None:
+        """Write procedure data to file."""
+        file_path = self._get_file_path(procedure_id)
+
+        try:
+            with open(file_path, "w") as f:
+                json.dump(data, f, indent=2, default=str)
+        except (IOError, OSError) as e:
+            raise RuntimeError(f"Failed to write procedure file {file_path}: {e}")
+
+    def load_procedure_metadata(self, procedure_id: str) -> ProcedureMetadata:
+        """Load procedure metadata from file."""
+        data = self._read_file(procedure_id)
+
+        if not data:
+            # Create new metadata
+            return ProcedureMetadata(procedure_id=procedure_id)
+
+        # Convert stored execution log back to CheckpointEntry objects
+        execution_log = []
+        for entry_data in data.get("execution_log", []):
+            # Rebuild SourceLocation if present
+            source_location = None
+            if entry_data.get("source_location"):
+                source_location = SourceLocation(**entry_data["source_location"])
+
+            execution_log.append(
+                CheckpointEntry(
+                    position=entry_data["position"],
+                    type=entry_data["type"],
+                    result=entry_data["result"],
+                    timestamp=datetime.fromisoformat(entry_data["timestamp"]),
+                    duration_ms=entry_data.get("duration_ms"),
+                    input_hash=entry_data.get("input_hash"),
+                    run_id=entry_data["run_id"],
+                    source_location=source_location,
+                    captured_vars=entry_data.get("captured_vars"),
+                )
+            )
+
+        return ProcedureMetadata(
+            procedure_id=procedure_id,
+            execution_log=execution_log,
+            replay_index=data.get("replay_index", 0),
+            state=data.get("state", {}),
+            lua_state=data.get("lua_state", {}),
+            status=data.get("status", "RUNNING"),
+            waiting_on_message_id=data.get("waiting_on_message_id"),
+        )
+
+    def save_procedure_metadata(self, procedure_id: str, metadata: ProcedureMetadata) -> None:
+        """Save procedure metadata to file."""
+        # Convert to serializable dict
+        data = {
+            "procedure_id": metadata.procedure_id,
+            "execution_log": [
+                {
+                    "position": entry.position,
+                    "type": entry.type,
+                    "result": entry.result,
+                    "timestamp": entry.timestamp.isoformat(),
+                    "duration_ms": entry.duration_ms,
+                    "input_hash": entry.input_hash,
+                    "run_id": entry.run_id,
+                    "source_location": (
+                        entry.source_location.model_dump() if entry.source_location else None
+                    ),
+                    "captured_vars": entry.captured_vars,
+                }
+                for entry in metadata.execution_log
+            ],
+            "replay_index": metadata.replay_index,
+            "state": metadata.state,
+            "lua_state": metadata.lua_state,
+            "status": metadata.status,
+            "waiting_on_message_id": metadata.waiting_on_message_id,
+        }
+
+        self._write_file(procedure_id, data)
+
+    def update_procedure_status(
+        self, procedure_id: str, status: str, waiting_on_message_id: Optional[str] = None
+    ) -> None:
+        """Update procedure status."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        metadata.status = status
+        metadata.waiting_on_message_id = waiting_on_message_id
+        self.save_procedure_metadata(procedure_id, metadata)
+
+    def get_state(self, procedure_id: str) -> Dict[str, Any]:
+        """Get mutable state dictionary."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        return metadata.state
+
+    def set_state(self, procedure_id: str, state: Dict[str, Any]) -> None:
+        """Set mutable state dictionary."""
+        metadata = self.load_procedure_metadata(procedure_id)
+        metadata.state = state
+        self.save_procedure_metadata(procedure_id, metadata)
+
+    # Tracing & Debugging Methods
+
+    def _load_index(self) -> Dict[str, Any]:
+        """Load the run index."""
+        if not self.index_file.exists():
+            return {}
+
+        try:
+            with open(self.index_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    def _save_index(self, index: Dict[str, Any]) -> None:
+        """Save the run index."""
+        try:
+            with open(self.index_file, "w") as f:
+                json.dump(index, f, indent=2, default=str)
+        except (IOError, OSError) as e:
+            raise RuntimeError(f"Failed to write index file: {e}")
+
+    def _update_index(self, run: ExecutionRun) -> None:
+        """Update index with run metadata."""
+        index = self._load_index()
+
+        index[run.run_id] = {
+            "procedure_name": run.procedure_name,
+            "file_path": run.file_path,
+            "start_time": run.start_time.isoformat(),
+            "status": run.status,
+        }
+
+        self._save_index(index)
+
+    def save_run(self, run: ExecutionRun) -> None:
+        """
+        Save complete run data.
+
+        Args:
+            run: Execution run to save
+        """
+        run_path = self.runs_dir / f"{run.run_id}.json"
+
+        # Convert to dict with proper serialization
+        data = run.model_dump()
+
+        # Convert datetime objects to ISO strings
+        if isinstance(data.get("start_time"), datetime):
+            data["start_time"] = data["start_time"].isoformat()
+        if data.get("end_time") and isinstance(data.get("end_time"), datetime):
+            data["end_time"] = data["end_time"].isoformat()
+
+        # Convert checkpoint timestamps
+        for checkpoint in data.get("execution_log", []):
+            if isinstance(checkpoint.get("timestamp"), datetime):
+                checkpoint["timestamp"] = checkpoint["timestamp"].isoformat()
+
+        try:
+            with open(run_path, "w") as f:
+                json.dump(data, f, indent=2, default=str)
+        except (IOError, OSError) as e:
+            raise RuntimeError(f"Failed to save run {run.run_id}: {e}")
+
+        # Update index
+        self._update_index(run)
+
+    def load_run(self, run_id: str) -> ExecutionRun:
+        """
+        Load complete run data.
+
+        Args:
+            run_id: Run identifier
+
+        Returns:
+            Execution run
+
+        Raises:
+            FileNotFoundError: If run not found
+        """
+        run_path = self.runs_dir / f"{run_id}.json"
+
+        if not run_path.exists():
+            raise FileNotFoundError(f"Run {run_id} not found")
+
+        try:
+            with open(run_path, "r") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, IOError) as e:
+            raise RuntimeError(f"Failed to load run {run_id}: {e}")
+
+        # Convert timestamps back to datetime objects
+        if data.get("start_time"):
+            data["start_time"] = datetime.fromisoformat(data["start_time"])
+        if data.get("end_time"):
+            data["end_time"] = datetime.fromisoformat(data["end_time"])
+
+        # Convert checkpoint timestamps and rebuild CheckpointEntry objects
+        execution_log = []
+        for cp_data in data.get("execution_log", []):
+            if cp_data.get("timestamp"):
+                cp_data["timestamp"] = datetime.fromisoformat(cp_data["timestamp"])
+
+            # Rebuild SourceLocation if present
+            if cp_data.get("source_location"):
+                cp_data["source_location"] = SourceLocation(**cp_data["source_location"])
+
+            execution_log.append(CheckpointEntry(**cp_data))
+
+        data["execution_log"] = execution_log
+
+        # Rebuild Breakpoint objects
+        breakpoints = []
+        for bp_data in data.get("breakpoints", []):
+            breakpoints.append(Breakpoint(**bp_data))
+
+        data["breakpoints"] = breakpoints
+
+        return ExecutionRun(**data)
+
+    def list_runs(self, procedure_name: Optional[str] = None) -> List[ExecutionRun]:
+        """
+        List all runs, optionally filtered by procedure name.
+
+        Args:
+            procedure_name: Optional procedure name filter
+
+        Returns:
+            List of execution runs, sorted by start time (newest first)
+        """
+        index = self._load_index()
+
+        # Filter by procedure name if specified
+        if procedure_name:
+            run_ids = [
+                rid for rid, info in index.items() if info.get("procedure_name") == procedure_name
+            ]
+        else:
+            run_ids = list(index.keys())
+
+        # Load all matching runs
+        runs = []
+        for run_id in run_ids:
+            try:
+                runs.append(self.load_run(run_id))
+            except (FileNotFoundError, RuntimeError):
+                # Skip corrupted or missing runs
+                continue
+
+        # Sort by start time (newest first)
+        runs.sort(key=lambda r: r.start_time, reverse=True)
+
+        return runs
+
+    def save_breakpoints(self, procedure_name: str, breakpoints: List[Breakpoint]) -> None:
+        """
+        Save breakpoints for a procedure.
+
+        Args:
+            procedure_name: Procedure name
+            breakpoints: List of breakpoints
+        """
+        bp_path = self.breakpoints_dir / f"{procedure_name}.json"
+
+        data = [bp.model_dump() for bp in breakpoints]
+
+        try:
+            with open(bp_path, "w") as f:
+                json.dump(data, f, indent=2)
+        except (IOError, OSError) as e:
+            raise RuntimeError(f"Failed to save breakpoints for {procedure_name}: {e}")
+
+    def load_breakpoints(self, procedure_name: str) -> List[Breakpoint]:
+        """
+        Load breakpoints for a procedure.
+
+        Args:
+            procedure_name: Procedure name
+
+        Returns:
+            List of breakpoints
+        """
+        bp_path = self.breakpoints_dir / f"{procedure_name}.json"
+
+        if not bp_path.exists():
+            return []
+
+        try:
+            with open(bp_path, "r") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return []
+
+        return [Breakpoint(**bp_data) for bp_data in data]

tactus/adapters/http_callback_log.py

@@ -0,0 +1,109 @@
+"""
+HTTP Callback Log Handler for container event streaming.
+
+Posts log events to a callback URL for real-time streaming from containers.
+Used when TACTUS_CALLBACK_URL environment variable is set.
+"""
+
+import logging
+import os
+from typing import Optional, List
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from tactus.protocols.models import LogEvent, CostEvent
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPCallbackLogHandler:
+    """
+    Log handler that POSTs events to an HTTP callback URL.
+
+    Used inside Docker containers to stream events back to the IDE backend.
+    The callback URL is provided via TACTUS_CALLBACK_URL environment variable.
+    """
+
+    def __init__(
+        self,
+        callback_url: str,
+        timeout: float = 5.0,
+        max_retries: int = 3,
+    ):
+        """
+        Initialize HTTP callback log handler.
+
+        Args:
+            callback_url: URL to POST events to
+            timeout: Request timeout in seconds
+            max_retries: Number of retries on failure
+        """
+        self.callback_url = callback_url
+        self.timeout = timeout
+        self.cost_events: List[CostEvent] = []  # Track cost events for aggregation
+
+        # Setup session with retry logic
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=max_retries,
+            backoff_factor=0.1,
+            status_forcelist=[429, 500, 502, 503, 504],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+        logger.info(f"[HTTP_CALLBACK] Initialized with URL: {callback_url}")
+
+    def log(self, event: LogEvent) -> None:
+        """
+        POST log event to callback URL.
+
+        Args:
+            event: Structured log event
+        """
+        # Track cost events for aggregation (mirrors IDELogHandler behavior)
+        if isinstance(event, CostEvent):
+            self.cost_events.append(event)
+
+        try:
+            # Serialize event to JSON
+            event_dict = event.model_dump(mode="json")
+
+            # Format timestamp to ensure ISO format with Z suffix
+            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
+
+            # POST to callback URL
+            response = self.session.post(
+                self.callback_url,
+                json=event_dict,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+            logger.debug(f"[HTTP_CALLBACK] Event posted: type={event.event_type}")
+
+        except requests.exceptions.RequestException as e:
+            # Log but don't fail - event streaming is best-effort
+            logger.warning(f"[HTTP_CALLBACK] Failed to POST event to {self.callback_url}: {e}")
+        except Exception as e:
+            # Catch any other errors to prevent crashing the procedure
+            logger.warning(f"[HTTP_CALLBACK] Unexpected error posting event: {e}")
+
+    @classmethod
+    def from_environment(cls) -> Optional["HTTPCallbackLogHandler"]:
+        """
+        Create handler from TACTUS_CALLBACK_URL environment variable.
+
+        Returns:
+            HTTPCallbackLogHandler if env var is set, None otherwise.
+        """
+        callback_url = os.environ.get("TACTUS_CALLBACK_URL")
+        if callback_url:
+            logger.info(f"[HTTP_CALLBACK] Creating handler from environment: {callback_url}")
+            return cls(callback_url=callback_url)
+        return None

tactus/adapters/ide_log.py

@@ -0,0 +1,71 @@
+"""
+IDE Log Handler for event collection and streaming.
+
+Collects log events in a queue for streaming to IDE frontend.
+"""
+
+import logging
+import queue
+from typing import List
+
+from tactus.protocols.models import LogEvent
+
+logger = logging.getLogger(__name__)
+
+
+class IDELogHandler:
+    """
+    IDE log handler that collects events for streaming.
+
+    Receives structured log events and stores them in a queue
+    for retrieval and streaming to the IDE frontend.
+    """
+
+    def __init__(self):
+        """Initialize IDE log handler."""
+        self.events = queue.Queue()
+        self.cost_events = []  # Track cost events for aggregation
+        logger.debug("IDELogHandler initialized")
+
+    def log(self, event: LogEvent) -> None:
+        """
+        Collect log event for streaming.
+
+        Args:
+            event: Structured log event
+        """
+        # Track cost events for aggregation
+        from tactus.protocols.models import CostEvent, AgentStreamChunkEvent
+
+        if isinstance(event, CostEvent):
+            self.cost_events.append(event)
+
+        # Debug logging for streaming events
+        if isinstance(event, AgentStreamChunkEvent):
+            logger.info(
+                f"[IDE_LOG] Received AgentStreamChunkEvent: agent={event.agent_name}, chunk_len={len(event.chunk_text)}, accumulated_len={len(event.accumulated_text)}"
+            )
+
+        self.events.put(event)
+        logger.debug(
+            f"[IDE_LOG] Event queued: type={type(event).__name__}, queue_size={self.events.qsize()}"
+        )
+
+    def get_events(self, timeout: float = 0.1) -> List[LogEvent]:
+        """
+        Get all available events from the queue.
+
+        Args:
+            timeout: Timeout for queue.get() in seconds
+
+        Returns:
+            List of LogEvent objects
+        """
+        events = []
+        while True:
+            try:
+                event = self.events.get(timeout=timeout)
+                events.append(event)
+            except queue.Empty:
+                break
+        return events