tactus 0.25.0__py3-none-any.whl → 0.27.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.25.0"
+__version__ = "0.27.0"
 
 # Core exports
 from tactus.core.runtime import TactusRuntime

tactus/adapters/broker_log.py

@@ -0,0 +1,55 @@
+"""
+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
+
+from typing import Optional
+
+from asyncer import syncify
+
+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] = []
+
+    @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:
+            syncify(self._client.emit_event)(event_dict)
+        except Exception:
+            # Swallow errors; container remains networkless and secretless even if streaming fails.
+            return

tactus/adapters/cli_hitl.py

@@ -32,7 +32,7 @@ class CLIHITLHandler:
             console: Rich Console instance (creates new one if not provided)
         """
         self.console = console or Console()
-        logger.info("CLIHITLHandler initialized")
+        logger.debug("CLIHITLHandler initialized")
 
     def request_interaction(self, procedure_id: str, request: HITLRequest) -> HITLResponse:
         """
@@ -45,7 +45,7 @@ class CLIHITLHandler:
         Returns:
             HITLResponse with user's response
         """
-        logger.info(f"HITL request: {request.request_type} - {request.message}")
+        logger.debug(f"HITL request: {request.request_type} - {request.message}")
 
         # Display the request in a panel
         self.console.print()

tactus/adapters/cli_log.py

@@ -72,13 +72,6 @@ class CLILogHandler:
             self._display_checkpoint_event(event)
             return
 
-        # Handle system alert events
-        from tactus.protocols.models import SystemAlertEvent
-
-        if isinstance(event, SystemAlertEvent):
-            self._display_system_alert_event(event)
-            return
-
         # Handle ExecutionSummaryEvent specially
         if event.event_type == "execution_summary":
             self._display_execution_summary(event)
@@ -191,24 +184,6 @@ class CLILogHandler:
                 f"{f' (saved ${event.cache_cost:.6f})' if event.cache_cost else ''}[/green]"
             )
 
-    def _display_system_alert_event(self, event) -> None:
-        """Display a System.alert() event."""
-        level = (event.level or "info").lower()
-        style = {
-            "info": "blue",
-            "warning": "yellow",
-            "error": "red",
-            "critical": "red bold",
-        }.get(level, "blue")
-
-        source_str = f" ({event.source})" if getattr(event, "source", None) else ""
-        self.console.print(f"[{style}]• Alert{source_str}:[/{style}] {event.message}")
-
-        if getattr(event, "context", None):
-            import json
-
-            self.console.print(f"  Context: {json.dumps(event.context, indent=2, default=str)}")
-
     def _display_execution_summary(self, event) -> None:
         """Display execution summary with cost breakdown."""
         self.console.print(

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)

tactus/broker/__init__.py

@@ -0,0 +1,12 @@
+"""
+Brokered capabilities for Tactus.
+
+The broker is a trusted host-side process that holds credentials and performs
+privileged operations (e.g., LLM API calls) on behalf of a secretless, networkless
+runtime container.
+"""
+
+from tactus.broker.client import BrokerClient
+from tactus.broker.server import BrokerServer, TcpBrokerServer
+
+__all__ = ["BrokerClient", "BrokerServer", "TcpBrokerServer"]

tactus/broker/client.py

@@ -0,0 +1,260 @@
+"""
+Broker client for use inside the runtime container.
+
+Uses a broker transport selected at runtime:
+- `stdio` (recommended for Docker Desktop): requests are written to stderr with a marker and
+  responses are read from stdin as NDJSON.
+- Unix domain sockets (UDS): retained for non-Docker/host testing.
+"""
+
+import asyncio
+import json
+import os
+import ssl
+import sys
+import threading
+import uuid
+from pathlib import Path
+from typing import Any, AsyncIterator, Optional
+
+from tactus.broker.stdio import STDIO_REQUEST_PREFIX, STDIO_TRANSPORT_VALUE
+
+
+def _json_dumps(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+
+
+class _StdioBrokerTransport:
+    def __init__(self):
+        self._write_lock = threading.Lock()
+        self._pending: dict[
+            str, tuple[asyncio.AbstractEventLoop, asyncio.Queue[dict[str, Any]]]
+        ] = {}
+        self._pending_lock = threading.Lock()
+        self._reader_thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+
+    def _ensure_reader_thread(self) -> None:
+        if self._reader_thread is not None and self._reader_thread.is_alive():
+            return
+
+        self._reader_thread = threading.Thread(
+            target=self._read_loop,
+            name="tactus-broker-stdio-reader",
+            daemon=True,
+        )
+        self._reader_thread.start()
+
+    def _read_loop(self) -> None:
+        while not self._stop.is_set():
+            line = sys.stdin.buffer.readline()
+            if not line:
+                return
+            try:
+                event = json.loads(line.decode("utf-8"))
+            except json.JSONDecodeError:
+                continue
+
+            req_id = event.get("id")
+            if not isinstance(req_id, str):
+                continue
+
+            with self._pending_lock:
+                pending = self._pending.get(req_id)
+            if pending is None:
+                continue
+
+            loop, queue = pending
+            try:
+                loop.call_soon_threadsafe(queue.put_nowait, event)
+            except RuntimeError:
+                # Loop is closed or unavailable; ignore.
+                continue
+
+    async def aclose(self) -> None:
+        self._stop.set()
+        thread = self._reader_thread
+        if thread is None or not thread.is_alive():
+            return
+        try:
+            await asyncio.to_thread(thread.join, 0.5)
+        except Exception:
+            return
+
+    async def request(
+        self, req_id: str, method: str, params: dict[str, Any]
+    ) -> AsyncIterator[dict[str, Any]]:
+        self._ensure_reader_thread()
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        with self._pending_lock:
+            self._pending[req_id] = (loop, queue)
+
+        try:
+            payload = _json_dumps({"id": req_id, "method": method, "params": params})
+            with self._write_lock:
+                sys.stderr.write(f"{STDIO_REQUEST_PREFIX}{payload}\n")
+                sys.stderr.flush()
+
+            while True:
+                event = await queue.get()
+                yield event
+                if event.get("event") in ("done", "error"):
+                    return
+        finally:
+            with self._pending_lock:
+                self._pending.pop(req_id, None)
+
+
+_STDIO_TRANSPORT = _StdioBrokerTransport()
+
+
+async def close_stdio_transport() -> None:
+    await _STDIO_TRANSPORT.aclose()
+
+
+class BrokerClient:
+    def __init__(self, socket_path: str | Path):
+        self.socket_path = str(socket_path)
+
+    @classmethod
+    def from_environment(cls) -> Optional["BrokerClient"]:
+        socket_path = os.environ.get("TACTUS_BROKER_SOCKET")
+        if not socket_path:
+            return None
+        return cls(socket_path)
+
+    async def _request(self, method: str, params: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        req_id = uuid.uuid4().hex
+
+        if self.socket_path == STDIO_TRANSPORT_VALUE:
+            async for event in _STDIO_TRANSPORT.request(req_id, method, params):
+                # Responses are already correlated by req_id; add a defensive filter anyway.
+                if event.get("id") == req_id:
+                    yield event
+            return
+
+        if self.socket_path.startswith(("tcp://", "tls://")):
+            use_tls = self.socket_path.startswith("tls://")
+            host_port = self.socket_path.split("://", 1)[1]
+            if "/" in host_port:
+                host_port = host_port.split("/", 1)[0]
+            if ":" not in host_port:
+                raise ValueError(
+                    f"Invalid broker endpoint: {self.socket_path}. Expected tcp://host:port or tls://host:port"
+                )
+            host, port_str = host_port.rsplit(":", 1)
+            try:
+                port = int(port_str)
+            except ValueError as e:
+                raise ValueError(f"Invalid broker port in endpoint: {self.socket_path}") from e
+
+            ssl_ctx: ssl.SSLContext | None = None
+            if use_tls:
+                ssl_ctx = ssl.create_default_context()
+                cafile = os.environ.get("TACTUS_BROKER_TLS_CA_FILE")
+                if cafile:
+                    ssl_ctx.load_verify_locations(cafile=cafile)
+
+                if os.environ.get("TACTUS_BROKER_TLS_INSECURE") in ("1", "true", "yes"):
+                    ssl_ctx.check_hostname = False
+                    ssl_ctx.verify_mode = ssl.CERT_NONE
+
+            reader, writer = await asyncio.open_connection(host, port, ssl=ssl_ctx)
+            writer.write(
+                (_json_dumps({"id": req_id, "method": method, "params": params}) + "\n").encode(
+                    "utf-8"
+                )
+            )
+            await writer.drain()
+
+            try:
+                while True:
+                    line = await reader.readline()
+                    if not line:
+                        return
+                    event = json.loads(line.decode("utf-8"))
+                    if event.get("id") != req_id:
+                        continue
+                    yield event
+                    if event.get("event") in ("done", "error"):
+                        return
+            finally:
+                try:
+                    writer.close()
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+        reader, writer = await asyncio.open_unix_connection(self.socket_path)
+        writer.write(
+            (_json_dumps({"id": req_id, "method": method, "params": params}) + "\n").encode("utf-8")
+        )
+        await writer.drain()
+
+        try:
+            while True:
+                line = await reader.readline()
+                if not line:
+                    return
+                event = json.loads(line.decode("utf-8"))
+                # Ignore unrelated messages (defensive; current server is 1-req/conn).
+                if event.get("id") != req_id:
+                    continue
+                yield event
+                if event.get("event") in ("done", "error"):
+                    return
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    def llm_chat(
+        self,
+        *,
+        provider: str,
+        model: str,
+        messages: list[dict[str, Any]],
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stream: bool,
+    ) -> AsyncIterator[dict[str, Any]]:
+        params: dict[str, Any] = {
+            "provider": provider,
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+        }
+        if temperature is not None:
+            params["temperature"] = temperature
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        return self._request("llm.chat", params)
+
+    async def call_tool(self, *, name: str, args: dict[str, Any]) -> Any:
+        """
+        Call an allowlisted host tool via the broker.
+
+        Returns the decoded `result` payload from the broker.
+        """
+        if not isinstance(name, str) or not name:
+            raise ValueError("tool name must be a non-empty string")
+        if not isinstance(args, dict):
+            raise ValueError("tool args must be an object")
+
+        async for event in self._request("tool.call", {"name": name, "args": args}):
+            event_type = event.get("event")
+            if event_type == "done":
+                data = event.get("data") or {}
+                return data.get("result")
+            if event_type == "error":
+                err = event.get("error") or {}
+                raise RuntimeError(err.get("message") or "Broker tool error")
+
+        raise RuntimeError("Broker tool call ended without a response")
+
+    async def emit_event(self, event: dict[str, Any]) -> None:
+        async for _ in self._request("events.emit", {"event": event}):
+            pass