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

tactus/core/execution_context.py

@@ -21,6 +21,7 @@ from tactus.protocols.models import (
     SourceLocation,
     ExecutionRun,
 )
+from tactus.core.exceptions import ProcedureWaitingForHuman
 
 logger = logging.getLogger(__name__)
 
@@ -153,9 +154,20 @@ class BaseExecutionContext(ExecutionContext):
         # Lua sandbox reference for debug.getinfo access
         self.lua_sandbox: Optional[Any] = None
 
+        # Rich metadata for HITL notifications
+        self.procedure_name: str = procedure_id  # Use procedure_id as default name
+        self.invocation_id: str = str(uuid.uuid4())
+        self._started_at: datetime = datetime.now(timezone.utc)
+        self._input_data: Any = None
+
         # Load procedure metadata (contains execution_log and replay_index)
         self.metadata = self.storage.load_procedure_metadata(procedure_id)
 
+        # CRITICAL: Reset replay_index to 0 when starting a new execution
+        # The replay_index tracks our position when replaying the execution_log
+        # It must start at 0 for each new run, even though it was incremented during the previous run
+        self.metadata.replay_index = 0
+
     def set_run_id(self, run_id: str) -> None:
         """Set the run_id for subsequent checkpoints in this execution."""
         self.current_run_id = run_id
@@ -175,6 +187,21 @@ class BaseExecutionContext(ExecutionContext):
         """Store reference to Lua sandbox for debug.getinfo access."""
         self.lua_sandbox = lua_sandbox
 
+    def set_procedure_metadata(
+        self, procedure_name: Optional[str] = None, input_data: Any = None
+    ) -> None:
+        """
+        Set rich metadata for HITL notifications.
+
+        Args:
+            procedure_name: Human-readable name for the procedure
+            input_data: Input data passed to the procedure
+        """
+        if procedure_name is not None:
+            self.procedure_name = procedure_name
+        if input_data is not None:
+            self._input_data = input_data
+
     def checkpoint(
         self,
         fn: Callable[[], Any],
@@ -187,17 +214,50 @@ class BaseExecutionContext(ExecutionContext):
         On replay, returns cached result from execution log.
         On first execution, runs fn(), records in log, and returns result.
         """
-        logger.debug(
-            f"[CHECKPOINT] checkpoint() called, type={checkpoint_type}, has_log_handler={self.log_handler is not None}"
+        logger.info(
+            f"[CHECKPOINT] checkpoint() called, type={checkpoint_type}, position={self.metadata.replay_index}, "
+            f"current_run_id={self.current_run_id}, has_log_handler={self.log_handler is not None}"
         )
         current_position = self.metadata.replay_index
 
         # Check if we're in replay mode (checkpoint exists at this position)
         if current_position < len(self.metadata.execution_log):
-            # Replay mode: return cached result
             entry = self.metadata.execution_log[current_position]
-            self.metadata.replay_index += 1
-            return entry.result
+            logger.info(
+                f"[CHECKPOINT] Found existing checkpoint at position {current_position}: "
+                f"type={entry.type}, run_id={entry.run_id}, result_type={type(entry.result).__name__}"
+            )
+
+            # CRITICAL: Only replay checkpoints from the CURRENT run
+            # Each new run should execute fresh, not use cached results from previous runs
+            if entry.run_id != self.current_run_id:
+                logger.info(
+                    f"[CHECKPOINT] Checkpoint is from DIFFERENT run "
+                    f"(checkpoint run_id={entry.run_id}, current run_id={self.current_run_id}), "
+                    f"executing fresh (NOT replaying)"
+                )
+                # Fall through to execute mode - this is a new run
+            # Special case: HITL checkpoints may have result=None if saved before response arrived
+            # In this case, re-execute to check for cached response from control loop
+            elif entry.result is None and checkpoint_type.startswith("hitl_"):
+                logger.info(
+                    f"[CHECKPOINT] HITL checkpoint at position {current_position} has no result, "
+                    f"re-executing to check for cached response"
+                )
+                # Fall through to execute mode - will check for cached response
+            else:
+                # Normal replay: return cached result from CURRENT run
+                self.metadata.replay_index += 1
+                logger.info(
+                    f"[CHECKPOINT] REPLAYING checkpoint at position {current_position}, "
+                    f"type={entry.type}, run_id={entry.run_id}, returning cached result"
+                )
+                return entry.result
+        else:
+            logger.info(
+                f"[CHECKPOINT] No checkpoint at position {current_position} "
+                f"(only {len(self.metadata.execution_log)} checkpoints exist), executing fresh"
+            )
 
         # Execute mode: run function with checkpoint scope tracking
         old_checkpoint_flag = self._inside_checkpoint
@@ -239,12 +299,56 @@ class BaseExecutionContext(ExecutionContext):
                     self.metadata.state.copy() if hasattr(self.metadata, "state") else None
                 ),
             )
+        except ProcedureWaitingForHuman:
+            # CRITICAL: For HITL checkpoints, we need to save the checkpoint BEFORE exiting
+            # This enables transparent resume - on restart, we'll have a checkpoint at this position
+            # with result=None, and the control loop will check for cached responses
+            duration_ms = (time.time() - start_time) * 1000
+            entry = CheckpointEntry(
+                position=current_position,
+                type=checkpoint_type,
+                result=None,  # Will be filled in when response arrives
+                timestamp=datetime.now(timezone.utc),
+                duration_ms=duration_ms,
+                run_id=self.current_run_id,
+                source_location=source_location,
+                captured_vars=(
+                    self.metadata.state.copy() if hasattr(self.metadata, "state") else None
+                ),
+            )
+            # Only append if checkpoint doesn't already exist (from previous failed attempt)
+            if current_position < len(self.metadata.execution_log):
+                # Checkpoint already exists - update it
+                logger.debug(
+                    f"[CHECKPOINT] Updating existing HITL checkpoint at position {current_position} before exit"
+                )
+                self.metadata.execution_log[current_position] = entry
+            else:
+                # New checkpoint - append and increment
+                logger.debug(
+                    f"[CHECKPOINT] Creating new HITL checkpoint at position {current_position} before exit"
+                )
+                self.metadata.execution_log.append(entry)
+                self.metadata.replay_index += 1
+
+            self.storage.save_procedure_metadata(self.procedure_id, self.metadata)
+            # Restore checkpoint flag and re-raise
+            self._inside_checkpoint = old_checkpoint_flag
+            raise
         finally:
             # Always restore checkpoint flag, even if fn() raises
             self._inside_checkpoint = old_checkpoint_flag
 
-        # Add to execution log
-        self.metadata.execution_log.append(entry)
+        # Add to execution log (or update if checkpoint already exists from HITL exit)
+        if current_position < len(self.metadata.execution_log):
+            # Checkpoint already exists (saved during HITL exit) - update it with the result
+            logger.debug(
+                f"[CHECKPOINT] Updating existing HITL checkpoint at position {current_position} with result"
+            )
+            self.metadata.execution_log[current_position] = entry
+        else:
+            # New checkpoint - append to log
+            self.metadata.execution_log.append(entry)
         self.metadata.replay_index += 1
 
         # Emit checkpoint created event if we have a log handler
@@ -298,8 +402,14 @@ class BaseExecutionContext(ExecutionContext):
 
         Delegates to the HITLHandler protocol implementation.
         """
+        logger.debug(
+            f"[HITL] wait_for_human called: type={request_type}, message={message[:50] if message else 'None'}, hitl_handler={self.hitl}"
+        )
         if not self.hitl:
             # No HITL handler - return default immediately
+            logger.warning(
+                f"[HITL] No HITL handler configured - returning default value: {default_value}"
+            )
             return HITLResponse(
                 value=default_value, responded_at=datetime.now(timezone.utc), timed_out=True
             )
@@ -315,7 +425,8 @@ class BaseExecutionContext(ExecutionContext):
         )
 
         # Delegate to HITL handler (may raise ProcedureWaitingForHuman)
-        return self.hitl.request_interaction(self.procedure_id, request)
+        # Pass self (execution_context) for deterministic request ID generation
+        return self.hitl.request_interaction(self.procedure_id, request, execution_context=self)
 
     def sleep(self, seconds: int) -> None:
         """
@@ -457,6 +568,152 @@ class BaseExecutionContext(ExecutionContext):
 
         return run_id
 
+    def get_subject(self) -> Optional[str]:
+        """
+        Return a human-readable subject line for this execution.
+
+        Returns:
+            Subject line combining procedure name and current checkpoint position
+        """
+        checkpoint_pos = self.next_position()
+        if self.procedure_name:
+            return f"{self.procedure_name} (checkpoint {checkpoint_pos})"
+        return f"Procedure {self.procedure_id} (checkpoint {checkpoint_pos})"
+
+    def get_started_at(self) -> Optional[datetime]:
+        """
+        Return when this execution started.
+
+        Returns:
+            Timestamp when execution context was created
+        """
+        return self._started_at
+
+    def get_input_summary(self) -> Optional[Dict[str, Any]]:
+        """
+        Return a summary of the initial input to this procedure.
+
+        Returns:
+            Dict of input data, or None if no input
+        """
+        if self._input_data is None:
+            return None
+
+        # If input_data is already a dict, return it
+        if isinstance(self._input_data, dict):
+            return self._input_data
+
+        # Otherwise wrap it in a dict
+        return {"value": self._input_data}
+
+    def get_conversation_history(self) -> Optional[List[Dict]]:
+        """
+        Return conversation history if available.
+
+        Returns:
+            List of conversation messages, or None if not tracked
+        """
+        # For now, return None - could be extended to track agent conversations
+        # in future implementations
+        return None
+
+    def get_prior_control_interactions(self) -> Optional[List[Dict]]:
+        """
+        Return list of prior HITL interactions in this execution.
+
+        Returns:
+            List of HITL checkpoint entries from execution log
+        """
+        if not self.metadata or not self.metadata.execution_log:
+            return None
+
+        # Filter execution log for HITL checkpoints
+        hitl_checkpoints = [
+            {
+                "position": entry.position,
+                "type": entry.type,
+                "timestamp": entry.timestamp.isoformat() if entry.timestamp else None,
+                "duration_ms": entry.duration_ms,
+            }
+            for entry in self.metadata.execution_log
+            if entry.type.startswith("hitl_")
+        ]
+
+        return hitl_checkpoints if hitl_checkpoints else None
+
+    def get_lua_source_line(self) -> Optional[int]:
+        """
+        Get the current source line from Lua debug.getinfo.
+
+        Returns:
+            Line number or None if unavailable
+        """
+        if not self.lua_sandbox:
+            return None
+
+        try:
+            # Access Lua debug module to get current line
+            debug_mod = self.lua_sandbox.globals().debug
+            if debug_mod and hasattr(debug_mod, "getinfo"):
+                # getinfo(2) gets info about the calling function
+                # We need to go up the stack to find the user's code
+                for level in range(2, 10):
+                    try:
+                        info = debug_mod.getinfo(level, "Sl")
+                        if info:
+                            line = info.get("currentline")
+                            source = info.get("source", "")
+                            # Skip internal sources (start with @)
+                            if line and line > 0 and not source.startswith("@"):
+                                return int(line)
+                    except Exception:
+                        break
+        except Exception as e:
+            logger.debug(f"Could not get Lua source line: {e}")
+
+        return None
+
+    def get_runtime_context(self) -> Dict[str, Any]:
+        """
+        Build RuntimeContext dict for HITL requests.
+
+        Captures source location, execution position, elapsed time, and backtrace.
+
+        Returns:
+            Dict with runtime context fields
+        """
+        # Calculate elapsed time
+        elapsed = 0.0
+        if self._started_at:
+            elapsed = (datetime.now(timezone.utc) - self._started_at).total_seconds()
+
+        # Get current source location
+        source_line = self.get_lua_source_line()
+
+        # Build backtrace from execution log
+        backtrace = []
+        if self.metadata and self.metadata.execution_log:
+            for entry in self.metadata.execution_log:
+                bt_entry = {
+                    "checkpoint_type": entry.type,
+                    "duration_ms": entry.duration_ms,
+                }
+                if entry.source_location:
+                    bt_entry["line"] = entry.source_location.line
+                    bt_entry["function_name"] = entry.source_location.function
+                backtrace.append(bt_entry)
+
+        return {
+            "source_line": source_line,
+            "source_file": self.current_tac_file,
+            "checkpoint_position": self.next_position(),
+            "procedure_name": self.procedure_name,
+            "invocation_id": self.invocation_id,
+            "started_at": self._started_at.isoformat() if self._started_at else None,
+            "elapsed_seconds": elapsed,
+            "backtrace": backtrace,
+        }
+
 
 class InMemoryExecutionContext(BaseExecutionContext):
     """

tactus/core/lua_sandbox.py

@@ -125,16 +125,14 @@ class LuaSandbox:
         # Whitelist only safe debug functions for source location tracking
         # Keep debug.getinfo but remove dangerous debug functions
         if "debug" in lua_globals:
-            self.lua.execute(
-                """
+            self.lua.execute("""
                 if debug then
                     local safe_debug = {
                         getinfo = debug.getinfo
                     }
                     debug = safe_debug
                 end
-            """
-            )
+            """)
             logger.debug("Replaced debug module with safe_debug (only getinfo allowed)")
 
     def _setup_safe_require(self):
@@ -158,11 +156,14 @@ class LuaSandbox:
         # Build search paths:
         # 1. User's project directory (existing behavior)
         # 2. Tactus stdlib .tac files
+        # Both single-file modules (?.tac) and directory modules (?/init.tac) are supported
         user_path = os.path.join(self.base_path, "?.tac")
+        user_init_path = os.path.join(self.base_path, "?", "init.tac")
         stdlib_path = os.path.join(stdlib_tac_path, "?.tac")
+        stdlib_init_path = os.path.join(stdlib_tac_path, "?", "init.tac")
 
         # Normalize backslashes for cross-platform compatibility
-        paths = [user_path, stdlib_path]
+        paths = [user_path, user_init_path, stdlib_path, stdlib_init_path]
         paths = [p.replace("\\", "/") for p in paths]
 
         # Join with Lua's path separator (semicolon)
@@ -202,8 +203,7 @@ class LuaSandbox:
 
         # Add to package.loaders (Lua 5.1) or package.searchers (Lua 5.2+)
         # Lupa uses LuaJIT which follows Lua 5.1 conventions
-        self.lua.execute(
-            """
+        self.lua.execute("""
             -- Add Python stdlib loader to package.loaders
             -- Insert after the preload loader but before path loader
             local loaders = package.loaders or package.searchers
@@ -221,8 +221,7 @@ class LuaSandbox:
                 -- Insert at position 2 (after preload, before path)
                 table.insert(loaders, 2, python_searcher)
             end
-        """
-        )
+        """)
 
         logger.debug("Python stdlib loader installed")
 

tactus/core/registry.py

@@ -155,6 +155,7 @@ class ProcedureRegistry(BaseModel):
 
     # Gherkin BDD Testing
     gherkin_specifications: Optional[str] = None  # Raw Gherkin text
+    specs_from_references: list[str] = Field(default_factory=list)  # External spec file paths
     custom_steps: dict[str, Any] = Field(default_factory=dict)  # step_text -> lua_function
     evaluation_config: dict[str, Any] = Field(default_factory=dict)  # runs, parallel, etc.
 
@@ -413,6 +414,17 @@ class RegistryBuilder:
         """Register Gherkin BDD specifications."""
         self.registry.gherkin_specifications = gherkin_text
 
+    def register_specs_from(self, file_path: str) -> None:
+        """Register a reference to external specifications.
+
+        Stores the path for lazy loading. Actual spec content
+        is loaded during test execution, not parse time.
+
+        Args:
+            file_path: Path to .spec.tac file or module name
+        """
+        self.registry.specs_from_references.append(file_path)
+
     def register_custom_step(self, step_text: str, lua_function: Any) -> None:
         """Register a custom step definition."""
         self.registry.custom_steps[step_text] = lua_function
@@ -479,11 +491,16 @@ class RegistryBuilder:
                 )
 
         # Warnings for missing specifications
-        if not self.registry.specifications and not self.registry.gherkin_specifications:
+        has_specs = (
+            self.registry.specifications
+            or self.registry.gherkin_specifications
+            or self.registry.specs_from_references
+        )
+        if not has_specs:
             warnings.append(
                 ValidationMessage(
                     level="warning",
-                    message="No specifications defined - consider adding BDD tests using specifications([[...]])",
+                    message='No specifications defined - consider adding BDD tests using Specification([[...]]) or Specification { from = "path" }',
                 )
             )