tactus 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

tactus/primitives/handles.py

@@ -149,12 +149,38 @@ class AgentHandle:
             logger.debug(
                 f"[CHECKPOINT] Creating checkpoint for agent '{self.name}', type=agent_turn, source_info={source_info}"
             )
-            return self._execution_context.checkpoint(
-                agent_call, checkpoint_type="agent_turn", source_info=source_info
-            )
-        else:
-            # No execution context - call directly without checkpointing
-            return self._primitive(converted_inputs)
+            result = self._execution_context.checkpoint(
+                agent_call, checkpoint_type="agent_turn", source_info=source_info
+            )
+        else:
+            # No execution context - call directly without checkpointing
+            result = self._primitive(converted_inputs)
+
+        # Convenience: expose the last agent output on the handle as `.output`
+        # for Lua patterns like `agent(); return agent.output`.
+        output_text = None
+        if result is not None:
+            for attr in ("response", "message"):
+                try:
+                    value = getattr(result, attr, None)
+                except Exception:
+                    value = None
+                if isinstance(value, str):
+                    output_text = value
+                    break
+
+            if output_text is None and isinstance(result, dict):
+                for key in ("response", "message"):
+                    value = result.get(key)
+                    if isinstance(value, str):
+                        output_text = value
+                        break
+
+            if output_text is None:
+                output_text = str(result)
+
+        self.output = output_text
+        return result
 
     def _set_primitive(
         self, primitive: "DSPyAgentHandle", execution_context: Optional[Any] = None
@@ -216,7 +242,8 @@ class ModelHandle:
                 f"Model '{self.name}' initialization failed.\n"
                 f"This should not happen - please report this as a bug."
             )
-        return self._primitive.predict(data)
+        converted_data = _convert_lua_table(data) if data is not None else None
+        return self._primitive.predict(converted_data)
 
     def __call__(self, data: Any = None) -> Any:
         """

tactus/primitives/host.py

@@ -0,0 +1,94 @@
+"""
+Host Primitive - brokered host capabilities for the runtime container.
+
+This primitive is intended to be used inside the sandboxed runtime container.
+It delegates allowlisted operations to the trusted host-side broker via the
+`TACTUS_BROKER_SOCKET` transport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+from tactus.broker.client import BrokerClient
+
+
+class HostPrimitive:
+    """Provides access to allowlisted host-side tools via the broker."""
+
+    def __init__(self, client: Optional[BrokerClient] = None):
+        self._client = client or BrokerClient.from_environment()
+        self._registry = None
+        if self._client is None:
+            # Allow Host.call() to work in non-sandboxed runs (and in deterministic tests)
+            # without requiring a broker transport, while still staying deny-by-default.
+            from tactus.broker.server import HostToolRegistry
+
+            self._registry = HostToolRegistry.default()
+
+    def _run_coro(self, coro):
+        """
+        Run an async coroutine from Lua's synchronous context.
+
+        Mirrors the approach used by `ToolHandle` for async tool handlers.
+        """
+        try:
+            asyncio.get_running_loop()
+
+            import threading
+
+            result_container = {"value": None, "exception": None}
+
+            def run_in_thread():
+                try:
+                    result_container["value"] = asyncio.run(coro)
+                except Exception as e:
+                    result_container["exception"] = e
+
+            thread = threading.Thread(target=run_in_thread)
+            thread.start()
+            thread.join()
+
+            if result_container["exception"]:
+                raise result_container["exception"]
+            return result_container["value"]
+
+        except RuntimeError:
+            return asyncio.run(coro)
+
+    def _lua_to_python(self, obj: Any) -> Any:
+        if obj is None:
+            return None
+        if hasattr(obj, "items") and not isinstance(obj, dict):
+            return {k: self._lua_to_python(v) for k, v in obj.items()}
+        if isinstance(obj, dict):
+            return {k: self._lua_to_python(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [self._lua_to_python(v) for v in obj]
+        return obj
+
+    def call(self, name: str, args: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Call an allowlisted host tool via the broker.
+
+        Example (Lua):
+            local result = Host.call("host.ping", {value = 1})
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("Host.call requires a non-empty tool name string")
+
+        args_dict = self._lua_to_python(args) or {}
+        if not isinstance(args_dict, dict):
+            raise ValueError("Host.call args must be an object/table")
+
+        if self._client is not None:
+            return self._run_coro(self._client.call_tool(name=name, args=args_dict))
+
+        if self._registry is not None:
+            try:
+                return self._registry.call(name, args_dict)
+            except KeyError as e:
+                raise RuntimeError(f"Tool not allowlisted: {name}") from e
+
+        raise RuntimeError("Host.call requires TACTUS_BROKER_SOCKET to be set")

tactus/primitives/log.py

@@ -150,6 +150,10 @@ class LogPrimitive:
             formatted = self._format_message(message, context)
             self.logger.warning(formatted)
 
+    def warning(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
+        """Alias for warn(), matching common logging APIs."""
+        self.warn(message, context)
+
     def error(self, message: str, context: Optional[Dict[str, Any]] = None) -> None:
         """
         Log error message.

tactus/primitives/model.py

@@ -3,7 +3,7 @@ Model primitive for ML inference with automatic checkpointing.
 """
 
 import logging
-from typing import Any
+from typing import Any, Optional
 
 from tactus.core.execution_context import ExecutionContext
 
@@ -23,7 +23,13 @@ class ModelPrimitive:
     Each .predict() call is automatically checkpointed for durability.
     """
 
-    def __init__(self, model_name: str, config: dict, context: ExecutionContext | None = None):
+    def __init__(
+        self,
+        model_name: str,
+        config: dict,
+        context: ExecutionContext | None = None,
+        mock_manager: Optional[Any] = None,
+    ):
         """
         Initialize model primitive.
 
@@ -39,6 +45,7 @@ class ModelPrimitive:
         self.model_name = model_name
         self.config = config
         self.context = context
+        self.mock_manager = mock_manager
 
         # Extract optional input/output schemas
         self.input_schema = config.get("input", {})
@@ -124,6 +131,17 @@ class ModelPrimitive:
         Returns:
             Model prediction result
         """
+        if self.mock_manager is not None:
+            args = input_data if isinstance(input_data, dict) else {"input": input_data}
+            mock_result = self.mock_manager.get_mock_response(self.model_name, args)
+            if mock_result is not None:
+                # Ensure temporal mocks advance and calls are available for assertions.
+                try:
+                    self.mock_manager.record_call(self.model_name, args, mock_result)
+                except Exception:
+                    pass
+                return mock_result
+
         return self.backend.predict_sync(input_data)
 
     def __call__(self, input_data: Any) -> Any:

tactus/primitives/procedure.py

@@ -75,6 +75,7 @@ class ProcedurePrimitive:
         self,
         execution_context: Any,
         runtime_factory: Callable[[str, Dict[str, Any]], Any],
+        lua_sandbox: Any = None,
         max_depth: int = 5,
         current_depth: int = 0,
     ):
@@ -84,11 +85,13 @@ class ProcedurePrimitive:
         Args:
             execution_context: Execution context for state management
             runtime_factory: Factory function to create TactusRuntime instances
+            lua_sandbox: LuaSandbox instance for in-file procedure lookup
             max_depth: Maximum recursion depth
             current_depth: Current recursion depth
         """
         self.execution_context = execution_context
         self.runtime_factory = runtime_factory
+        self.lua_sandbox = lua_sandbox
         self.max_depth = max_depth
         self.current_depth = current_depth
         self.handles: Dict[str, ProcedureHandle] = {}
@@ -96,6 +99,28 @@ class ProcedurePrimitive:
 
         logger.info(f"ProcedurePrimitive initialized (depth {current_depth}/{max_depth})")
 
+    def __call__(self, name: str) -> Any:
+        """
+        Look up an in-file named procedure by name.
+
+        Enables Lua syntax:
+            local res = Procedure("my_proc")({ ... })
+
+        Named procedures are injected into Lua globals by the runtime during initialization.
+        """
+        if not self.lua_sandbox or not hasattr(self.lua_sandbox, "lua"):
+            raise ProcedureExecutionError("Procedure lookup is not available (lua_sandbox missing)")
+
+        try:
+            proc = self.lua_sandbox.lua.globals()[name]
+        except Exception:
+            proc = None
+
+        if proc is None:
+            raise ProcedureExecutionError(f"Named procedure '{name}' not found")
+
+        return proc
+
     def run(self, name: str, params: Optional[Dict[str, Any]] = None) -> Any:
         """
         Synchronous procedure invocation with auto-checkpointing.
@@ -122,6 +147,12 @@ class ProcedurePrimitive:
 
         # Normalize params
         params = params or {}
+        if hasattr(params, "items"):
+            from tactus.core.dsl_stubs import lua_table_to_dict
+
+            params = lua_table_to_dict(params)
+            if isinstance(params, list) and len(params) == 0:
+                params = {}
 
         # Wrap execution in checkpoint for durability
         def execute_procedure():
@@ -134,26 +165,37 @@ class ProcedurePrimitive:
 
                 # Execute synchronously (runtime.execute is async, so we need to run it)
                 import asyncio
+                import threading
+
+                async def run_subprocedure():
+                    return await runtime.execute(source=source, context=params, format="lua")
 
                 try:
-                    loop = asyncio.get_running_loop()
-                    # We're already in an async context, use run_until_complete would fail
-                    # Instead, we need to await it, but we're in a sync function
-                    # Solution: Create a task and wait for it
-                    result = asyncio.create_task(
-                        runtime.execute(source=source, context=params, format="lua")
-                    )
-                    # This won't work in sync context - we need to handle this differently
-                    # For now, use run_until_complete in a new loop
-                    raise RuntimeError("Cannot run nested async in sync context")
+                    asyncio.get_running_loop()
+                    has_running_loop = True
                 except RuntimeError:
-                    # No running loop or nested loop issue - create new one
-                    loop = asyncio.new_event_loop()
-                    asyncio.set_event_loop(loop)
-                    result = loop.run_until_complete(
-                        runtime.execute(source=source, context=params, format="lua")
-                    )
-                    loop.close()
+                    has_running_loop = False
+
+                if has_running_loop:
+                    result_holder = {}
+                    error_holder = {}
+
+                    def run_in_thread():
+                        try:
+                            result_holder["result"] = asyncio.run(run_subprocedure())
+                        except Exception as e:
+                            error_holder["error"] = e
+
+                    t = threading.Thread(target=run_in_thread, daemon=True)
+                    t.start()
+                    t.join()
+
+                    if "error" in error_holder:
+                        raise error_holder["error"]
+
+                    result = result_holder.get("result")
+                else:
+                    result = asyncio.run(run_subprocedure())
 
                 # Extract result from execution response
                 if result.get("success"):
@@ -469,41 +511,54 @@ class ProcedurePrimitive:
         Raises:
             FileNotFoundError: If procedure file not found
         """
-        import os
         from pathlib import Path
 
-        # Build search paths
-        search_paths = [
-            name,  # Exact path
-            f"{name}.tac",  # Add extension
-        ]
-
-        # Add paths relative to the current procedure file's directory
-        if (
-            hasattr(self.execution_context, "current_tac_file")
-            and self.execution_context.current_tac_file
-        ):
-            current_file = Path(self.execution_context.current_tac_file)
-            current_dir = current_file.parent
-            search_paths.extend(
-                [
-                    str(current_dir / name),  # Relative to current file
-                    str(current_dir / f"{name}.tac"),  # Relative with extension
-                ]
-            )
-
-        # Add examples directory as fallback
-        search_paths.extend(
-            [
-                f"examples/{name}",  # Examples directory
-                f"examples/{name}.tac",  # Examples with extension
-            ]
-        )
+        search_paths: list[Path] = []
+        seen: set[Path] = set()
+
+        def add_path(path: Path) -> None:
+            normalized = path.resolve() if path.is_absolute() else path
+            if normalized in seen:
+                return
+            seen.add(normalized)
+            search_paths.append(path)
+
+        name_path = Path(name)
+
+        def add_candidates(base: Path | None, rel: Path) -> None:
+            candidate = (base / rel) if base is not None else rel
+            add_path(candidate)
+            if candidate.suffix != ".tac":
+                add_path(Path(str(candidate) + ".tac"))
+
+        # Absolute path: try as-is.
+        if name_path.is_absolute():
+            add_candidates(None, name_path)
+        else:
+            # Relative to current working directory (CLI usage).
+            add_candidates(None, name_path)
+
+            # Relative to the current .tac file directory and its parents (BDD/temp cwd usage).
+            current_tac_file = getattr(self.execution_context, "current_tac_file", None)
+            if current_tac_file:
+                current_dir = Path(current_tac_file).parent
+                add_candidates(current_dir, name_path)
+
+                # Also try resolving from parent directories (helps when callers pass paths
+                # relative to project root, but cwd is not the project root).
+                for parent in list(current_dir.parents)[:5]:
+                    add_candidates(parent, name_path)
+
+            # Fallback: examples directory relative to repo root in common layouts.
+            add_candidates(None, Path("examples") / name_path)
 
         for path in search_paths:
-            if os.path.exists(path):
-                logger.debug(f"Loading procedure from: {path}")
-                with open(path, "r") as f:
-                    return f.read()
-
-        raise FileNotFoundError(f"Procedure '{name}' not found. Searched: {search_paths}")
+            try:
+                if path.exists() and path.is_file():
+                    logger.debug(f"Loading procedure from: {path}")
+                    return path.read_text()
+            except Exception:
+                continue
+
+        searched = [str(p) for p in search_paths]
+        raise FileNotFoundError(f"Procedure '{name}' not found. Searched: {searched}")

tactus/primitives/tool.py

@@ -22,8 +22,6 @@ class ToolCall:
 
     def __init__(self, name: str, args: Dict[str, Any], result: Any):
         self.name = name
-        # Backward/compatibility alias used by some callers
-        self.tool_name = name
         self.args = args
         self.result = result
         self.timestamp = None  # Could add timestamp tracking

tactus/protocols/__init__.py

@@ -13,10 +13,6 @@ from tactus.protocols.models import (
     ChatMessage,
 )
 
-# Shared usage/cost + standard result
-from tactus.protocols.cost import UsageStats, CostStats
-from tactus.protocols.result import TactusResult
-
 # Protocols
 from tactus.protocols.storage import StorageBackend
 from tactus.protocols.hitl import HITLHandler
@@ -32,9 +28,6 @@ __all__ = [
     "HITLRequest",
     "HITLResponse",
     "ChatMessage",
-    "UsageStats",
-    "CostStats",
-    "TactusResult",
     # Protocols
     "StorageBackend",
     "HITLHandler",

tactus/protocols/log_handler.py

@@ -6,7 +6,7 @@ Implementations can render logs differently (CLI with Rich, IDE with React, etc.
 """
 
 from typing import Protocol, Union
-from tactus.protocols.models import ExecutionSummaryEvent, LogEvent, SystemAlertEvent
+from tactus.protocols.models import LogEvent, ExecutionSummaryEvent
 
 
 class LogHandler(Protocol):
@@ -17,7 +17,7 @@ class LogHandler(Protocol):
     appropriately for different environments (CLI, IDE, API, etc.).
     """
 
-    def log(self, event: Union[LogEvent, ExecutionSummaryEvent, SystemAlertEvent]) -> None:
+    def log(self, event: Union[LogEvent, ExecutionSummaryEvent]) -> None:
         """
         Handle a log or summary event.
 

tactus/protocols/models.py

@@ -203,7 +203,7 @@ class CostEvent(BaseModel):
 
     # Response data (new field)
     response_data: Optional[Dict[str, Any]] = Field(
-        None, description="Agent's response data (extracted from result.value)"
+        None, description="Agent's response data (extracted from result.data)"
     )
 
     model_config = {"arbitrary_types_allowed": True}

tactus/sandbox/config.py

@@ -26,12 +26,12 @@ class SandboxConfig(BaseModel):
 
     # Core settings
     # Security model:
-    # - enabled=None (default): Sandbox REQUIRED, error if Docker unavailable
+    # - enabled=None (default): Sandbox AUTO (use if available; otherwise run without isolation)
     # - enabled=True: Sandbox REQUIRED, error if Docker unavailable
     # - enabled=False: Sandbox explicitly disabled (security risk acknowledged)
     enabled: Optional[bool] = Field(
         default=None,
-        description="Enable sandbox mode. None/True=required (error if unavailable), False=disabled",
+        description="Enable sandbox mode. None=auto, True=required, False=disabled",
     )
 
     # Docker image settings
@@ -60,10 +60,38 @@ class SandboxConfig(BaseModel):
 
     # Network mode
     network: str = Field(
-        default="bridge",
+        default="none",
         description="Docker network mode (bridge allows outbound, none blocks all)",
     )
 
+    # Broker transport (how the secretless runtime reaches the host broker)
+    # - stdio: local Docker MVP (works on Docker Desktop with --network none)
+    # - tcp/tls: remote-mode spike (for K8s/cloud; requires container networking)
+    broker_transport: str = Field(
+        default="stdio",
+        description="Broker transport for the runtime container: stdio, tcp, or tls",
+    )
+    broker_host: str = Field(
+        default="host.docker.internal",
+        description="Broker hostname for tcp/tls (as seen from inside the container)",
+    )
+    broker_bind_host: str = Field(
+        default="0.0.0.0",
+        description="Bind address for the host-side broker server in tcp/tls modes",
+    )
+    broker_port: int = Field(
+        default=0,
+        description="Port for the host-side broker server in tcp/tls modes (0=auto)",
+    )
+    broker_tls_cert_file: Optional[str] = Field(
+        default=None,
+        description="TLS certificate file for broker (PEM). Required when broker_transport='tls'",
+    )
+    broker_tls_key_file: Optional[str] = Field(
+        default=None,
+        description="TLS private key file for broker (PEM). Required when broker_transport='tls'",
+    )
+
     # Resource limits
     limits: SandboxLimits = Field(
         default_factory=SandboxLimits,
@@ -109,9 +137,9 @@ class SandboxConfig(BaseModel):
 
         Returns:
             True if Docker unavailability should be a fatal error.
-            This is True unless the user explicitly disabled sandbox.
+            This is True only when the user explicitly requires the sandbox (enabled=True).
         """
-        return not self.is_explicitly_disabled()
+        return self.enabled is True
 
     model_config = {"arbitrary_types_allowed": True}