tactus 0.26.0__tar.gz → 0.27.0__tar.gz

{tactus-0.26.0 → tactus-0.27.0}/.gitignore

@@ -39,6 +39,8 @@ progress.output
 .tac/
 tmp/
 examples/output/
+_recovery/
+.tactus-broker/
 
 *storybook.log
 storybook-static

{tactus-0.26.0 → tactus-0.27.0}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- version list -->
 
+## v0.27.0 (2026-01-11)
+
+### Features
+
+- **broker**: Brokered sandbox runtime MVP (secretless runtime container) (#24)
+  ([#24](https://github.com/AnthusAI/Tactus/pull/24),
+  [`f922432`](https://github.com/AnthusAI/Tactus/commit/f922432da5a881c5eceb7c1410276ab45264ddaa))
+
+
 ## v0.26.0 (2026-01-11)
 
 ### Features

{tactus-0.26.0 → tactus-0.27.0}/Makefile

@@ -1,4 +1,5 @@
 .PHONY: help generate-parsers generate-python-parser generate-typescript-parser test-parsers clean-generated dev-ide test-examples test-examples-fast test-examples-parallel test-examples-bdd
+.PHONY: test-docker-sandbox
 
 help:
 	@echo "Tactus Parser Generation and Testing"
@@ -17,6 +18,9 @@ help:
 	@echo "  test-examples-parallel  - Test examples in parallel for speed"
 	@echo "  test-examples-bdd       - Test only examples with BDD specifications"
 	@echo ""
+	@echo "Docker Sandbox Testing:"
+	@echo "  test-docker-sandbox     - Run opt-in Docker sandbox smoke tests"
+	@echo ""
 	@echo "Requirements:"
 	@echo "  - Docker must be running (for parser generation)"
 	@echo "  - Python 3.11+ with dependencies installed"
@@ -113,6 +117,11 @@ test-examples-bdd:
 	@echo "Testing examples with BDD specifications..."
 	pytest tests/testing/test_all_examples.py::TestAllExamples::test_example_bdd_specs -v --tb=short
 
+# Docker sandbox integration tests (dev-only, opt-in)
+test-docker-sandbox:
+	@echo "Running Docker sandbox integration tests (opt-in)..."
+	@echo "Pre-req: tactus sandbox rebuild --force"
+	TACTUS_RUN_DOCKER_TESTS=1 pytest -m docker -v --tb=short
 
 
 

{tactus-0.26.0 → tactus-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.26.0
+Version: 0.27.0
 Summary: Tactus: Lua-based DSL for agentic workflows
 Project-URL: Homepage, https://github.com/AnthusAI/Tactus
 Project-URL: Documentation, https://github.com/AnthusAI/Tactus/tree/main/docs

{tactus-0.26.0 → tactus-0.27.0}/docs/DURABILITY.md

@@ -1097,7 +1097,7 @@ class AgentPrimitive:
         )
         return {
             "output": result.output,
-            "messages": self.messages
+            "messages": self.messages + result.new_messages()
         }
 ```
 
@@ -1390,4 +1390,4 @@ result = await runtime.execute(
 
 4. **Observability**: Integration with Logfire/OpenTelemetry for tracing?
 
-5. **Error recovery**: Retry policies, dead letter queues, manual intervention?
+5. **Error recovery**: Retry policies, dead letter queues, manual intervention?

{tactus-0.26.0 → tactus-0.27.0}/docs/SANDBOXING.md

@@ -1,6 +1,6 @@
 # Sandboxing & Security
 
-Tactus provides **three layers of sandboxing** to protect against different threat models. This defense-in-depth approach makes Tactus safe for user-contributed code, secure for local development, and production-ready for multi-tenant AI systems.
+Tactus provides **three layers of sandboxing** to protect against different threat models. This defense-in-depth approach makes Tactus safe for user-contributed code, secure for local development, and designed to support secure multi-tenant AI systems.
 
 ## Overview: Three Layers of Protection
 
@@ -458,6 +458,7 @@ logger.info(f"Tool call: {tool_name}", extra={
 ## Development
 - [ ] Docker Desktop installed and running
 - [ ] Sandbox enabled in config (default)
+- [ ] Run opt-in Docker sandbox tests (dev-only): `tactus sandbox rebuild --force` then `make test-docker-sandbox` (or `TACTUS_RUN_DOCKER_TESTS=1 pytest -m docker -v`)
 - [ ] MCP servers reviewed for security issues
 - [ ] Tool calls logged for debugging
 - [ ] Resource limits configured appropriately
@@ -485,7 +486,7 @@ logger.info(f"Tool call: {tool_name}", extra={
 2. **Default security:** Sandbox enabled by default, opt-out requires explicit acknowledgment
 3. **AI-native design:** Built from the ground up to prevent session leakage
 4. **Embeddable safety:** Lua sandboxing makes Tactus safe for user-contributed code
-5. **Production-ready:** Cloud sandboxing provides multi-tenant isolation at scale
+5. **Multi-tenant isolation:** Cloud sandboxing provides per-invocation isolation at scale
 6. **Information security DNA:** Per-invocation sandboxing prevents AI session leakage, a critical requirement for multi-tenant AI systems
 
 ---

{tactus-0.26.0 → tactus-0.27.0}/docs/TOOLS.md

@@ -1,23 +1,33 @@
-# Defining Tools with Lua Functions
+# Tools in Tactus
 
-This guide explains how to define tools as Lua functions within Tactus procedures, giving agents the ability to perform custom operations without requiring external Python plugins or MCP servers.
+This guide explains the major tool types in Tactus, where they run, and how to keep secrets out of sandboxed runs.
 
 ## Table of Contents
 
 1. [Overview](#overview)
-2. [Quick Start](#quick-start)
-3. [Three Approaches](#three-approaches)
-4. [Parameter Specifications](#parameter-specifications)
-5. [Tool Implementation Patterns](#tool-implementation-patterns)
-6. [Error Handling](#error-handling)
-7. [Tool Call Tracking](#tool-call-tracking)
-8. [Advanced Examples](#advanced-examples)
-9. [Comparison with Plugin Tools](#comparison-with-plugin-tools)
-10. [Best Practices](#best-practices)
+2. [Trust Zones](#trust-zones)
+3. [Brokered Host Tools](#brokered-host-tools)
+4. [Quick Start](#quick-start)
+5. [Three Approaches](#three-approaches)
+6. [Parameter Specifications](#parameter-specifications)
+7. [Tool Implementation Patterns](#tool-implementation-patterns)
+8. [Error Handling](#error-handling)
+9. [Tool Call Tracking](#tool-call-tracking)
+10. [Advanced Examples](#advanced-examples)
+11. [Comparison with Plugin Tools](#comparison-with-plugin-tools)
+12. [Best Practices](#best-practices)
 
 ## Overview
 
-Tactus supports three ways to define tools as Lua functions:
+Tactus supports several tool types:
+
+- **Built-in Tactus tools** (shipped with Tactus): e.g. `tactus.tools.done`
+- **Lua function tools** (defined inside `.tac`): simple, fast, co-located with the workflow
+- **Python plugin tools** (loaded from `tool_paths`): run Python code from your repo without MCP
+- **MCP tools** (Model Context Protocol): tools provided by external stdio servers
+- **Brokered host tools** (Phase 1B): privileged “host-side” tools executed by the broker and invoked from the sandbox via `Host.call(...)`
+
+Lua function tools support three ways to define tools:
 
 1. **Individual `tool()` declarations** - Define single tools globally
 2. **`toolset()` with `type="lua"`** - Group multiple related tools
@@ -33,6 +43,53 @@ All three approaches are powered by Pydantic AI's function toolset feature and i
 - **Tracked**: Full integration with `Tool.called()` and `Tool.last_call()`
 - **Fast**: Minimal overhead for simple operations
 
+## Trust Zones
+
+Tactus aims to keep the **runtime container** (when using `--sandbox`) both:
+
+- **Networkless** by default (`--network none`)
+- **Secretless** (no long-lived API keys in the container env, mounts, or request payload)
+
+That means not all “tools” are equal: different tool types run in different trust zones.
+
+At a high level:
+
+- **Lua tools** run inside the runtime (and therefore inside the sandbox container when `--sandbox` is enabled).
+- **MCP servers** run as subprocesses of the runtime (so they share the runtime’s trust zone unless explicitly isolated).
+- **Brokered host tools** run on the trusted host-side broker and can hold secrets without exposing them to the sandbox.
+
+For the broader architecture (including future isolated tool runners), see `planning/BROKER_AND_TOOL_RUNNERS.md`.
+
+## Brokered Host Tools
+
+Brokered host tools are allowlisted operations executed by the **host-side broker** and invoked from the runtime via the `Host` primitive.
+
+This is the core mechanism for “remote tools with secrets” (e.g., a Tab search API key) while keeping the sandbox container secretless.
+
+### Running the Example
+
+Run the example:
+
+```bash
+tactus sandbox rebuild --force
+tactus run examples/66-host-tools-via-broker.tac --sandbox --verbose
+```
+
+Call a host tool from Lua:
+
+```lua
+local result = Host.call("host.ping", {value = 1})
+```
+
+### Default Allowlist (Phase 1B)
+
+The default broker allowlist intentionally starts small:
+
+- `host.ping`
+- `host.echo`
+
+To add real host tools, extend the broker’s allowlist (see `tactus/broker/server.py:HostToolRegistry`).
+
 ## Quick Start
 
 Here's the simplest example:
@@ -652,7 +709,7 @@ content_editor = Agent {
 - Lua language constraints
 - No async operations
 - Limited to Lua ecosystem
-- Can't call external APIs directly
+- Can't safely hold secrets (use brokered host tools instead)
 
 **Best for:**
 - Data transformations
@@ -683,6 +740,23 @@ content_editor = Agent {
 - Shared across projects
 - Complex algorithms
 
+### Brokered Host Tools (via Host.call)
+
+**Pros:**
+- Secrets stay out of the sandbox container
+- Can perform network calls without giving the runtime network access
+- Centralized allowlist and auditing point (the broker)
+
+**Cons:**
+- Requires a broker transport (`--sandbox` uses broker by default)
+- Must be explicitly allowlisted (deny-by-default)
+- Privileged by design; treat host tools as trusted code
+
+**Best for:**
+- Remote API tools that require API keys
+- “Host-integrated” capabilities (e.g., talking to a local index, keychain, or daemon)
+- Anything that must be kept out of the untrusted runtime container
+
 ### When to Use Which?
 
 Use **Lua Function Tools** when:
@@ -705,6 +779,11 @@ Use **MCP Tools** when:
 - Tool is maintained separately
 - Multiple procedures share it
 
+Use **Brokered Host Tools** when:
+- A tool needs secrets but the runtime container must remain secretless
+- The runtime container must remain networkless (`--network none`)
+- You want a narrow, allowlisted capability surface area
+
 ## Best Practices
 
 ### 1. Clear Descriptions

{tactus-0.26.0 → tactus-0.27.0}/docs/TOOL_ROADMAP.md

@@ -1126,7 +1126,7 @@ sequenceDiagram
     PA->>LLM: Send tool result
     LLM-->>PA: Final response
     PA-->>AP: RunResult
-    AP-->>Lua: Result
+    AP-->>Lua: ResultPrimitive
 
     Lua->>Lua: search.called()
     Lua->>Lua: search.last_result()

tactus-0.27.0/examples/01-basics-hello-world.tac

@@ -0,0 +1,23 @@
+World = Agent {
+    provider = "openai",
+    model = "gpt-4o-mini",
+    system_prompt = "Your name is World.",
+    module = "Raw"  -- No DSPy delimiter formatting
+}
+
+Procedure {
+    output = {
+        message = field.string{required = true}
+    },
+    function(_)
+        local result = World({message = "Hello, World!"})
+        return {message = result.response}
+    end
+}
+
+Mocks {
+    World = {
+        tool_calls = {},
+        message = "Hello, World!"
+    }
+}

{tactus-0.26.0 → tactus-0.27.0}/examples/05-basics-multi-model.tac

@@ -45,7 +45,7 @@ Procedure {
         if done.called() then
             research = done.last_result() or "Task completed"
         else
-            research = tostring(result.value) or "Research not completed"
+            research = result.message or "Research not completed"
             Log.warn("Researcher did not call done within max turns")
         end
         state.research = research
@@ -66,7 +66,7 @@ Procedure {
         if done.called() then
             summary = done.last_result() or "Task completed"
         else
-            summary = tostring(result.value) or "Summary not completed"
+            summary = result.message or "Summary not completed"
             Log.warn("Summarizer did not call done within max turns")
         end
 

{tactus-0.26.0 → tactus-0.27.0}/examples/06-basics-streaming.tac

@@ -26,8 +26,15 @@ Procedure {
         local result = storyteller({message = input.prompt})
 
         return {
-            story = result.value,
+            story = result.response,
             success = true
         }
     end
 }
+
+Mocks {
+    storyteller = {
+        tool_calls = {},
+        message = "A curious robot dipped its brush into blue paint and discovered joy in every stroke."
+    }
+}

{tactus-0.26.0 → tactus-0.27.0}/examples/07-basics-bedrock.tac

@@ -36,9 +36,9 @@ Procedure {
             local response = haiku_assistant()
             turn_count = turn_count + 1
 
-            -- Accumulate the response value from each turn using .value property
-            if response.value and response.value ~= "" then
-                response_text = response_text .. response.value
+            -- Accumulate the response message from each turn using .message property
+            if response.message and response.message ~= "" then
+                response_text = response_text .. response.message
             end
 
             -- Safety check: exit if too many turns

{tactus-0.26.0 → tactus-0.27.0}/examples/08-basics-models.tac

@@ -137,8 +137,8 @@ Procedure {
                     local response = agent_ref()
                     turn_count = turn_count + 1
 
-                    if response.value and response.value ~= "" then
-                        response_text = response_text .. response.value
+                    if response.message and response.message ~= "" then
+                        response_text = response_text .. response.message
                     end
 
                     if turn_count >= max_turns then
@@ -175,7 +175,7 @@ Procedure {
             local success, result = pcall(function(input)
                 local response = agent_ref()
                 return {
-                    response = response.value or "",
+                    response = response.message or "",
                     turns = 1,
                     success = true,
                     error = nil

{tactus-0.26.0 → tactus-0.27.0}/examples/09-basics-google-gemini.tac

@@ -56,8 +56,8 @@ Procedure {
             pro_turns = pro_turns + 1
 
             -- Accumulate the response text
-            if response.value and response.value ~= "" then
-                pro_response = pro_response .. response.value
+            if response.message and response.message ~= "" then
+                pro_response = pro_response .. response.message
             end
 
             -- Safety check
@@ -86,8 +86,8 @@ Procedure {
             flash_turns = flash_turns + 1
 
             -- Accumulate the response text
-            if response.value and response.value ~= "" then
-                flash_response = flash_response .. response.value
+            if response.message and response.message ~= "" then
+                flash_response = flash_response .. response.message
             end
 
             -- Safety check

{tactus-0.26.0 → tactus-0.27.0}/examples/12-feature-structured-output.tac

@@ -1,11 +1,11 @@
 -- Structured Output Demo
 -- Demonstrates using output for structured data extraction
--- and accessing result.value, result.usage
+-- and accessing result.data, result.usage
 
 extractor = Agent {
     provider = "openai",
     model = "gpt-4o-mini",
-    system_prompt = [[You extract city information. Return ONLY a JSON object with these fields:
+    system_prompt = [[You extract city information. Return ONLY structured data with these fields:
 - city: city name
 - country: country name
 - population: estimated population (number, optional)
@@ -32,14 +32,14 @@ Procedure {
     function(input)
         Log.info("Starting structured output demo", {query = input.query})
 
-        -- Agent returns a Result wrapper (not raw data)
+        -- Agent returns ResultPrimitive (not raw data)
         local result = extractor()
 
-        -- Access structured data via result.value
+        -- Access structured data via result.data
         Log.info("Extracted city information", {
-            city = result.value.city,
-            country = result.value.country,
-            population = result.value.population or "unknown"
+            city = result.data.city,
+            country = result.data.country,
+            population = result.data.population or "unknown"
         })
 
         -- Access token usage stats
@@ -49,8 +49,20 @@ Procedure {
             total_tokens = result.usage.total_tokens
         })
 
+        -- Access messages from this turn
+        local new_msgs = result.new_messages()
+        Log.info("Messages generated in this turn", {count = #new_msgs})
+
+        -- Log first message (if any)
+        if #new_msgs > 0 then
+            Log.info("First message", {
+                role = new_msgs[1].role,
+                content_preview = string.sub(new_msgs[1].content, 1, 100)
+            })
+        end
+
         return {
-            city_data = result.value,
+            city_data = result.data,
             tokens_used = result.usage.total_tokens
         }
     end

{tactus-0.26.0 → tactus-0.27.0}/examples/14-feature-per-turn-tools-simple.tac

@@ -50,4 +50,13 @@ Procedure {
         return {success = true}
 
     end
-}
+}
+
+Mocks {
+    tester = {
+        tool_calls = {
+            {tool = "done", args = {reason = "Completed per-turn tool control demo"}}
+        },
+        message = "No tools available"
+    }
+}

{tactus-0.26.0 → tactus-0.27.0}/examples/15-feature-local-tools.tac

@@ -83,7 +83,7 @@ Procedure {
             end
         else
             -- Max turns reached - use last response
-            answer = tostring(result.value)
+            answer = result.message
         end
 
         return {
@@ -92,3 +92,13 @@ Procedure {
         }
     end
 }
+
+Mocks {
+    assistant = {
+        tool_calls = {
+            {tool = "calculate_mortgage", args = {principal = 300000, annual_interest_rate = 0.065, years = 30}},
+            {tool = "done", args = {reason = "Monthly payment is $1,896.20 (mocked)."}}
+        },
+        message = "Monthly payment is $1,896.20 (mocked)."
+    }
+}

{tactus-0.26.0 → tactus-0.27.0}/examples/16-feature-toolsets-advanced.tac

@@ -103,7 +103,7 @@ Procedure {
                 turn_count = turn_count + 1
             until done.called() or turn_count >= max_turns
 
-            local response = tostring(result.value)
+            local response = result.message
             Log.info(agent_name .. " response", {text = response})
             return response
         end
@@ -123,7 +123,7 @@ Procedure {
         -- Test Agent 5: No tools (explicitly empty) - only needs 1 turn
         Log.info("Testing Agent 5: No tools")
         local observer_result = observer()
-        local observer_response = tostring(observer_result.value)
+        local observer_response = observer_result.message
         Log.info("Observer response", {text = observer_response})
 
         return {

{tactus-0.26.0 → tactus-0.27.0}/examples/17-feature-toolsets-dsl.tac

@@ -94,8 +94,7 @@ Procedure {
         else
             Log.warn("Agent did not call done within max turns")
             return {
-                calculation_result = (result and result.value and tostring(result.value))
-                    or "Agent did not complete",
+                calculation_result = result.message or "Agent did not complete",
                 completed = false
             }
         end

{tactus-0.26.0 → tactus-0.27.0}/examples/18-feature-lua-tools-individual.tac

@@ -110,7 +110,7 @@ Procedure {
         if done.called() then
             answer = done.last_result() or "Task completed"
         else
-            answer = tostring(result.value)
+            answer = result.message
         end
 
         return {

{tactus-0.26.0 → tactus-0.27.0}/examples/18-feature-lua-tools-inline.tac

@@ -140,7 +140,7 @@ Procedure {
         if done.called() then
             answer = done.last_result() or "Task completed"
         else
-            answer = tostring(result.value)
+            answer = result.message
         end
 
         if #tools_used > 0 then

{tactus-0.26.0 → tactus-0.27.0}/examples/18-feature-lua-tools-toolset.tac

@@ -158,7 +158,7 @@ Procedure {
         if done.called() then
             answer = done.last_result() or "Task completed"
         else
-            answer = tostring(result.value)
+            answer = result.message
         end
 
         return {

{tactus-0.26.0 → tactus-0.27.0}/examples/40-model-text-classifier.tac

@@ -47,29 +47,17 @@ Procedure {
     },
     function(input)
 
-    -- Simple sentiment detection for demo/testing
-        -- Note: Model primitive mocking not yet implemented, using simple heuristic
-        local msg_lower = string.lower(input.customer_message)
-        if string.find(msg_lower, "love") or string.find(msg_lower, "great") or string.find(msg_lower, "amazing") then
-            State.sentiment = "positive"
-        elseif string.find(msg_lower, "hate") or string.find(msg_lower, "terrible") or string.find(msg_lower, "awful") then
-            State.sentiment = "negative"
-        else
-            State.sentiment = "neutral"
-        end
+    -- 1. Classify sentiment with ML model (checkpointed)
+        State.sentiment = Model("sentiment_classifier").predict({
+            text = input.customer_message
+        })
 
-        -- Agent responds based on sentiment (checkpointed)
+        -- 2. Agent responds based on sentiment (checkpointed)
         support_agent({message = input.customer_message})
 
-        -- Get response from done tool
-        local response = "Thank you for your message."
-        if done.called() then
-            response = done.last_result() or "I'm here to help."
-        end
-
         return {
             sentiment = State.sentiment,
-            response = response
+            response = support_agent.output
         }
 
     -- BDD Specifications
@@ -78,6 +66,9 @@ Procedure {
 
 -- Agent Mocks for CI testing
 Mocks {
+    sentiment_classifier = {
+        returns = "positive"
+    },
     support_agent = {
         tool_calls = {
             {tool = "done", args = {reason = "I'm happy to help! Thank you for your positive feedback."}}

{tactus-0.26.0 → tactus-0.27.0}/examples/41-model-pytorch.tac

@@ -13,7 +13,7 @@ local done = require("tactus.tools.done")
 
 -- Define a PyTorch sentiment classifier
 -- (This requires the .pt file to exist and PyTorch to be installed)
--- Model "sentiment_classifier" { type = "pytorch", path = "models/sentiment.pt" }
+Model "sentiment_classifier" { type = "pytorch", path = "models/sentiment.pt" }
 
 support_agent = Agent {
     provider = "openai",
@@ -31,7 +31,7 @@ Call done when finished.
 
 Procedure {
     input = {
-            customer_message = field.string{required = true, description = "Customer message to analyze"}
+            customer_message = field.string{default = "I love this product!", description = "Customer message to analyze"}
     },
     output = {
             sentiment = field.string{required = true, description = "Detected sentiment label"},
@@ -39,29 +39,16 @@ Procedure {
     },
     function(input)
 
-    -- Simple sentiment detection for demo/testing
-        -- Note: PyTorch model mocking not yet implemented, using simple heuristic
-        local msg_lower = string.lower(input.customer_message)
-        if string.find(msg_lower, "love") or string.find(msg_lower, "great") then
-            State.sentiment = "positive"
-        elseif string.find(msg_lower, "hate") or string.find(msg_lower, "bad") then
-            State.sentiment = "negative"
-        else
-            State.sentiment = "neutral"
-        end
+    -- Classify sentiment with PyTorch model
+        -- Input: tensor of word indices (for demo, just pass a simple tensor)
+        State.sentiment = Model("sentiment_classifier").predict({1, 2, 3, 4, 5})
 
         -- Agent responds based on sentiment
         support_agent({message = input.customer_message})
 
-        -- Get response from done tool
-        local response = "I'm here to help."
-        if done.called() then
-            response = done.last_result() or "Thank you for your message."
-        end
-
         return {
             sentiment = State.sentiment,
-            response = response
+            response = support_agent.output
         }
 
     -- BDD Specifications
@@ -70,6 +57,9 @@ Procedure {
 
 -- Agent Mocks for CI testing
 Mocks {
+    sentiment_classifier = {
+        returns = "positive"
+    },
     support_agent = {
         tool_calls = {
             {tool = "done", args = {reason = "Based on the sentiment analysis, I've provided an appropriate response."}}
@@ -82,7 +72,6 @@ Specifications([[
 Feature: PyTorch Model Integration
   Scenario: PyTorch model performs inference
     Given the procedure has started
-    And the input customer_message is "I love this product!"
     When the procedure runs
     Then the done tool should be called
     And the output sentiment should exist