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

tactus/broker/server.py

@@ -0,0 +1,505 @@
+"""
+Host-side broker server (local UDS transport).
+
+This is intentionally narrow: it exposes only allowlisted operations required
+by the runtime container.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import ssl
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _json_dumps(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"))
+
+
+async def _write_event(writer: asyncio.StreamWriter, event: dict[str, Any]) -> None:
+    writer.write((_json_dumps(event) + "\n").encode("utf-8"))
+    await writer.drain()
+
+
+@dataclass(frozen=True)
+class OpenAIChatConfig:
+    api_key_env: str = "OPENAI_API_KEY"
+
+
+class OpenAIChatBackend:
+    """
+    Minimal OpenAI chat-completions backend used by the broker.
+
+    Credentials are read from the broker process environment.
+    """
+
+    def __init__(self, config: Optional[OpenAIChatConfig] = None):
+        self._config = config or OpenAIChatConfig()
+
+        # Lazy-init the client so unit tests can run without OpenAI installed/configured.
+        self._client = None
+
+    def _get_client(self):
+        if self._client is not None:
+            return self._client
+
+        from openai import AsyncOpenAI
+
+        api_key = os.environ.get(self._config.api_key_env)
+        if not api_key:
+            raise RuntimeError(f"Missing OpenAI API key in environment: {self._config.api_key_env}")
+
+        self._client = AsyncOpenAI(api_key=api_key)
+        return self._client
+
+    async def chat(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        stream: bool,
+    ):
+        client = self._get_client()
+
+        kwargs: dict[str, Any] = {"model": model, "messages": messages}
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        if stream:
+            return await client.chat.completions.create(**kwargs, stream=True)
+
+        return await client.chat.completions.create(**kwargs)
+
+
+class HostToolRegistry:
+    """
+    Minimal deny-by-default registry for broker-executed host tools.
+
+    Phase 1B starts with a tiny allowlist and expands deliberately.
+    """
+
+    def __init__(self, tools: Optional[dict[str, Callable[[dict[str, Any]], Any]]] = None):
+        self._tools = tools or {}
+
+    @classmethod
+    def default(cls) -> "HostToolRegistry":
+        def host_ping(args: dict[str, Any]) -> dict[str, Any]:
+            return {"ok": True, "echo": args}
+
+        def host_echo(args: dict[str, Any]) -> dict[str, Any]:
+            return {"echo": args}
+
+        return cls({"host.ping": host_ping, "host.echo": host_echo})
+
+    def call(self, name: str, args: dict[str, Any]) -> Any:
+        if name not in self._tools:
+            raise KeyError(f"Tool not allowlisted: {name}")
+        return self._tools[name](args)
+
+
+class _BaseBrokerServer:
+    def __init__(
+        self,
+        *,
+        openai_backend: Optional[OpenAIChatBackend] = None,
+        tool_registry: Optional[HostToolRegistry] = None,
+        event_handler: Optional[Callable[[dict[str, Any]], None]] = None,
+    ):
+        self._server: Optional[asyncio.AbstractServer] = None
+        self._openai = openai_backend or OpenAIChatBackend()
+        self._tools = tool_registry or HostToolRegistry.default()
+        self._event_handler = event_handler
+
+    async def start(self) -> None:
+        raise NotImplementedError
+
+    async def aclose(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    async def __aenter__(self) -> "_BaseBrokerServer":
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    async def _handle_connection(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            line = await reader.readline()
+            if not line:
+                return
+
+            req = json.loads(line.decode("utf-8"))
+            req_id = req.get("id")
+            method = req.get("method")
+            params = req.get("params") or {}
+
+            if not req_id or not method:
+                await _write_event(
+                    writer,
+                    {
+                        "id": req_id or "",
+                        "event": "error",
+                        "error": {"type": "BadRequest", "message": "Missing id/method"},
+                    },
+                )
+                return
+
+            if method == "events.emit":
+                await self._handle_events_emit(req_id, params, writer)
+                return
+
+            if method == "llm.chat":
+                await self._handle_llm_chat(req_id, params, writer)
+                return
+
+            if method == "tool.call":
+                await self._handle_tool_call(req_id, params, writer)
+                return
+
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "MethodNotFound", "message": f"Unknown method: {method}"},
+                },
+            )
+
+        except Exception as e:
+            logger.debug("[BROKER] Connection handler error", exc_info=True)
+            try:
+                await _write_event(
+                    writer,
+                    {
+                        "id": "",
+                        "event": "error",
+                        "error": {"type": type(e).__name__, "message": str(e)},
+                    },
+                )
+            except Exception:
+                pass
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def _handle_events_emit(
+        self, req_id: str, params: dict[str, Any], writer: asyncio.StreamWriter
+    ) -> None:
+        event = params.get("event")
+        if not isinstance(event, dict):
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.event must be an object"},
+                },
+            )
+            return
+
+        try:
+            if self._event_handler is not None:
+                self._event_handler(event)
+        except Exception:
+            logger.debug("[BROKER] event_handler raised", exc_info=True)
+
+        await _write_event(writer, {"id": req_id, "event": "done", "data": {"ok": True}})
+
+    async def _handle_llm_chat(
+        self, req_id: str, params: dict[str, Any], writer: asyncio.StreamWriter
+    ) -> None:
+        provider = params.get("provider") or "openai"
+        if provider != "openai":
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {
+                        "type": "UnsupportedProvider",
+                        "message": f"Unsupported provider: {provider}",
+                    },
+                },
+            )
+            return
+
+        model = params.get("model")
+        messages = params.get("messages")
+        stream = bool(params.get("stream", False))
+        temperature = params.get("temperature")
+        max_tokens = params.get("max_tokens")
+
+        if not isinstance(model, str) or not model:
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.model must be a string"},
+                },
+            )
+            return
+        if not isinstance(messages, list):
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.messages must be a list"},
+                },
+            )
+            return
+
+        try:
+            if stream:
+                stream_iter = await self._openai.chat(
+                    model=model,
+                    messages=messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    stream=True,
+                )
+
+                full_text = ""
+                async for chunk in stream_iter:
+                    try:
+                        delta = chunk.choices[0].delta
+                        text = getattr(delta, "content", None)
+                    except Exception:
+                        text = None
+
+                    if not text:
+                        continue
+
+                    full_text += text
+                    await _write_event(
+                        writer, {"id": req_id, "event": "delta", "data": {"text": text}}
+                    )
+
+                await _write_event(
+                    writer,
+                    {
+                        "id": req_id,
+                        "event": "done",
+                        "data": {
+                            "text": full_text,
+                            "usage": {
+                                "prompt_tokens": 0,
+                                "completion_tokens": 0,
+                                "total_tokens": 0,
+                            },
+                        },
+                    },
+                )
+                return
+
+            resp = await self._openai.chat(
+                model=model,
+                messages=messages,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                stream=False,
+            )
+            text = ""
+            try:
+                text = resp.choices[0].message.content or ""
+            except Exception:
+                text = ""
+
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "done",
+                    "data": {
+                        "text": text,
+                        "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0},
+                    },
+                },
+            )
+        except Exception as e:
+            logger.debug("[BROKER] llm.chat error", exc_info=True)
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": type(e).__name__, "message": str(e)},
+                },
+            )
+
+    async def _handle_tool_call(
+        self, req_id: str, params: dict[str, Any], writer: asyncio.StreamWriter
+    ) -> None:
+        name = params.get("name")
+        args = params.get("args") or {}
+
+        if not isinstance(name, str) or not name:
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.name must be a string"},
+                },
+            )
+            return
+        if not isinstance(args, dict):
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": "BadRequest", "message": "params.args must be an object"},
+                },
+            )
+            return
+
+        try:
+            result = self._tools.call(name, args)
+        except KeyError:
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {
+                        "type": "ToolNotAllowed",
+                        "message": f"Tool not allowlisted: {name}",
+                    },
+                },
+            )
+            return
+        except Exception as e:
+            logger.debug("[BROKER] tool.call error", exc_info=True)
+            await _write_event(
+                writer,
+                {
+                    "id": req_id,
+                    "event": "error",
+                    "error": {"type": type(e).__name__, "message": str(e)},
+                },
+            )
+            return
+
+        await _write_event(writer, {"id": req_id, "event": "done", "data": {"result": result}})
+
+
+class BrokerServer(_BaseBrokerServer):
+    """
+    Local broker server that listens on a Unix domain socket.
+
+    Protocol (NDJSON):
+      request: {"id":"...","method":"llm.chat","params":{...}}
+      response stream:
+        {"id":"...","event":"delta","data":{"text":"..."}}
+        {"id":"...","event":"done","data":{...}}
+      or:
+        {"id":"...","event":"error","error":{"message":"...","type":"..."}}
+    """
+
+    def __init__(
+        self,
+        socket_path: Path,
+        *,
+        openai_backend: Optional[OpenAIChatBackend] = None,
+        tool_registry: Optional[HostToolRegistry] = None,
+        event_handler: Optional[Callable[[dict[str, Any]], None]] = None,
+    ):
+        super().__init__(
+            openai_backend=openai_backend, tool_registry=tool_registry, event_handler=event_handler
+        )
+        self.socket_path = Path(socket_path)
+
+    async def start(self) -> None:
+        # Most platforms enforce a short maximum length for AF_UNIX socket paths.
+        # Keep a conservative bound to avoid opaque "AF_UNIX path too long" errors.
+        if len(str(self.socket_path)) > 90:
+            raise ValueError(
+                f"Broker socket path too long for AF_UNIX: {self.socket_path} "
+                f"(len={len(str(self.socket_path))})"
+            )
+
+        self.socket_path.parent.mkdir(parents=True, exist_ok=True)
+        if self.socket_path.exists():
+            self.socket_path.unlink()
+
+        self._server = await asyncio.start_unix_server(
+            self._handle_connection, path=str(self.socket_path)
+        )
+        logger.info(f"[BROKER] Listening on UDS: {self.socket_path}")
+
+    async def aclose(self) -> None:
+        await super().aclose()
+
+        try:
+            if self.socket_path.exists():
+                self.socket_path.unlink()
+        except Exception:
+            logger.debug("[BROKER] Failed to unlink socket path", exc_info=True)
+
+
+class TcpBrokerServer(_BaseBrokerServer):
+    """
+    Broker server that listens on TCP (optionally TLS).
+
+    Protocol is the same NDJSON framing used by the UDS broker.
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str = "127.0.0.1",
+        port: int = 0,
+        ssl_context: ssl.SSLContext | None = None,
+        openai_backend: Optional[OpenAIChatBackend] = None,
+        tool_registry: Optional[HostToolRegistry] = None,
+        event_handler: Optional[Callable[[dict[str, Any]], None]] = None,
+    ):
+        super().__init__(
+            openai_backend=openai_backend, tool_registry=tool_registry, event_handler=event_handler
+        )
+        self.host = host
+        self.port = port
+        self.ssl_context = ssl_context
+        self.bound_port: int | None = None
+
+    async def start(self) -> None:
+        self._server = await asyncio.start_server(
+            self._handle_connection,
+            host=self.host,
+            port=self.port,
+            ssl=self.ssl_context,
+        )
+
+        sockets = self._server.sockets or []
+        if sockets:
+            try:
+                sockname = sockets[0].getsockname()
+                self.bound_port = int(sockname[1])
+            except Exception:
+                self.bound_port = None
+
+        scheme = "tls" if self.ssl_context is not None else "tcp"
+        logger.info(
+            f"[BROKER] Listening on {scheme}: {self.host}:{self.bound_port if self.bound_port is not None else self.port}"
+        )

tactus/broker/stdio.py

@@ -0,0 +1,12 @@
+"""
+Shared constants for broker-over-stdio transport.
+
+Docker Desktop (macOS/Windows) containers cannot connect to a host AF_UNIX socket
+bind-mounted from the host OS. For sandboxed runs we therefore use a broker RPC
+channel over the container process stdio.
+"""
+
+STDIO_TRANSPORT_VALUE = "stdio"
+
+# Container → host requests are written to stderr with this prefix, followed by a JSON object.
+STDIO_REQUEST_PREFIX = "<<<TACTUS_BROKER>>>"

tactus/cli/app.py

@@ -455,6 +455,21 @@ def run(
         help="Run in Docker sandbox (default: required unless --no-sandbox). "
         "Use --no-sandbox to run without isolation (security risk).",
     ),
+    sandbox_broker: str = typer.Option(
+        "stdio",
+        "--sandbox-broker",
+        help="Broker transport for sandbox runtime: stdio (default, --network none) or tcp/tls (remote-mode spike).",
+    ),
+    sandbox_network: Optional[str] = typer.Option(
+        None,
+        "--sandbox-network",
+        help="Docker network mode for sandbox container (default: none for stdio; bridge for tcp/tls).",
+    ),
+    sandbox_broker_host: Optional[str] = typer.Option(
+        None,
+        "--sandbox-broker-host",
+        help="Broker hostname from inside the sandbox container (tcp/tls only).",
+    ),
 ):
     """
     Run a Tactus workflow.
@@ -611,6 +626,19 @@ def run(
     if sandbox is not None:
         # CLI flag overrides config
         sandbox_config_dict["enabled"] = sandbox
+    if sandbox_network is not None:
+        sandbox_config_dict["network"] = sandbox_network
+    if sandbox_broker_host is not None:
+        sandbox_config_dict["broker_host"] = sandbox_broker_host
+
+    sandbox_config_dict["broker_transport"] = sandbox_broker
+    if (
+        sandbox_network is None
+        and sandbox_broker in ("tcp", "tls")
+        and "network" not in sandbox_config_dict
+    ):
+        # Remote-mode requires container networking; default to bridge if user didn't specify.
+        sandbox_config_dict["network"] = "bridge"
     sandbox_config = SandboxConfig(**sandbox_config_dict)
 
     # Pass logging preferences through to the sandbox container so container stderr matches CLI UX.
@@ -632,6 +660,11 @@ def run(
                 "[yellow][SANDBOX] Container isolation disabled (--no-sandbox or config).[/yellow]"
             )
             console.print("[yellow][SANDBOX] Proceeding without Docker isolation.[/yellow]")
+        elif not docker_available and not sandbox_config.should_error_if_unavailable():
+            # Sandbox is auto-mode (default): fall back when Docker is unavailable
+            console.print(
+                f"[yellow][SANDBOX] Docker not available ({docker_reason}); running without container isolation.[/yellow]"
+            )
         elif sandbox_config.should_error_if_unavailable() and not docker_available:
             # Sandbox required but Docker unavailable - ERROR
             console.print(f"[red][SANDBOX ERROR] Docker not available: {docker_reason}[/red]")
@@ -731,14 +764,17 @@ def run(
 
     try:
         if use_sandbox:
+            # Host-side broker reads OpenAI credentials from the host process environment.
+            # Keep secrets OUT of the sandbox container by setting the env var only on the host.
+            if api_key:
+                os.environ["OPENAI_API_KEY"] = api_key
+
             # Execute in Docker sandbox
             runner = ContainerRunner(sandbox_config)
             sandbox_result = asyncio.run(
                 runner.run(
                     source=source_content,
                     params=context,
-                    config=merged_config,
-                    mcp_servers=mcp_servers,
                     source_file_path=str(workflow_file),
                     format=file_format,
                 )

tactus/core/dsl_stubs.py

@@ -951,7 +951,8 @@ def create_dsl_stubs(
                 agent_config = {
                     "tool_calls": mock_config.get("tool_calls", []),
                     "message": mock_config.get("message", ""),
-                    "data": mock_config.get("data"),
+                    "data": mock_config.get("data", {}),
+                    "usage": mock_config.get("usage", {}),
                 }
                 builder.register_agent_mock(name, agent_config)
                 continue

tactus/core/output_validator.py

@@ -75,10 +75,13 @@ class OutputValidator:
         # If no schema defined, accept any output
         if not self.schema:
             logger.debug("No output schema defined, skipping validation")
-            # Convert Lua table to dict if needed, otherwise return as-is
-            if hasattr(output, "items") and not isinstance(output, dict):
+            if isinstance(output, dict):
+                return output
+            elif hasattr(output, "items"):
+                # Lua table - convert to dict
                 return dict(output.items())
-            return output
+            else:
+                return {"result": output}
 
         # Convert Lua tables to dicts recursively
         if hasattr(output, "items") or isinstance(output, dict):

tactus/core/registry.py

@@ -119,7 +119,14 @@ class AgentMockConfig(BaseModel):
     tool_calls: list[dict[str, Any]] = Field(default_factory=list)
     # List of tool calls to simulate: [{"tool": "done", "args": {"reason": "..."}}, ...]
     message: str = ""  # The agent's final message response
-    data: Optional[dict[str, Any]] = None  # Structured output data (for result.value)
+    data: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Optional structured response payload (exposed as result.data in Lua)",
+    )
+    usage: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Optional token usage payload (exposed as result.usage in Lua)",
+    )
 
 
 class ProcedureRegistry(BaseModel):