tactus 0.27.0__tar.gz → 0.28.0__tar.gz

{tactus-0.27.0 → tactus-0.28.0}/.github/workflows/release.yml

@@ -3,11 +3,13 @@ name: Release
 on:
   push:
     branches:
-      - main
+      - '**'
+  pull_request:
+    branches:
+      - '**'
 
 permissions:
-  contents: write
-  id-token: write
+  contents: read
 
 jobs:
   quality-checks:
@@ -38,7 +40,7 @@ jobs:
         run: black --check tactus/ tests/ features/steps/
 
       - name: Run pytest tests
-        run: pytest tests/ -v --tb=short -m "not integration"
+        run: pytest tests/ -v --tb=short -m "not integration" -n0
 
       - name: Run behave BDD tests
         run: behave
@@ -47,6 +49,10 @@ jobs:
     name: Semantic Release
     runs-on: ubuntu-latest
     needs: quality-checks
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      id-token: write
 
     steps:
       - name: Checkout code

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

@@ -2,6 +2,61 @@
 
 <!-- version list -->
 
+## v0.28.0 (2026-01-14)
+
+### Bug Fixes
+
+- Correct test assertions for protocol changes
+  ([`79b1bdb`](https://github.com/AnthusAI/Tactus/commit/79b1bdb6d4fd1e5c6dd5e7bd0089d2049d05ede8))
+
+- Disallow curried Tool syntax (#27) ([#27](https://github.com/AnthusAI/Tactus/pull/27),
+  [`e5b25c2`](https://github.com/AnthusAI/Tactus/commit/e5b25c23f1ba50e1fed1b8a13fef77c172ed48ab))
+
+- Enable TCP broker streaming with length-prefixed protocol
+  ([`68d4d91`](https://github.com/AnthusAI/Tactus/commit/68d4d915316928b9ce180737259363b49f38788b))
+
+- Mark broker integration tests to skip in CI
+  ([`a34de74`](https://github.com/AnthusAI/Tactus/commit/a34de74f083a229c7e6480ac80984808e9d76207))
+
+- Mark TCP broker integration tests to skip in CI
+  ([`e8ecfa5`](https://github.com/AnthusAI/Tactus/commit/e8ecfa5216c19b7339e342c2e8682265f25a2808))
+
+- Update DSPy agent tests for TactusResult API changes
+  ([`aeb16f0`](https://github.com/AnthusAI/Tactus/commit/aeb16f0d0bd45481840bdc26cb1ecc1b4d46c8a7))
+
+- Update TCP unit tests for length-prefixed protocol
+  ([`803bcd8`](https://github.com/AnthusAI/Tactus/commit/803bcd87b294082b2e598be4c299a8840f2be6f6))
+
+- **agent**: Make Raw the default module and case-insensitive matching
+  ([`0cac3fa`](https://github.com/AnthusAI/Tactus/commit/0cac3fa75b3ee49b6e87221eea5d232b9e751ca7))
+
+- **agent**: Return TactusResult with value and cost stats
+  ([`c83f92d`](https://github.com/AnthusAI/Tactus/commit/c83f92dd561b553f7db8cf32cb9a93e9dfad1b20))
+
+- **broker**: Handle async event emission from sync threads
+  ([`340e288`](https://github.com/AnthusAI/Tactus/commit/340e28891bcaefb174d5d2babb34a16f0c3abd84))
+
+### Chores
+
+- Update GitHub Actions workflow for release process
+  ([`310a5a5`](https://github.com/AnthusAI/Tactus/commit/310a5a5e07028257b04811d5a8e8e1fca2d34d90))
+
+### Code Style
+
+- Run black on test_mock_field_normalization.py
+  ([`4522f4b`](https://github.com/AnthusAI/Tactus/commit/4522f4b7e2e093d3041cea086d84efcece5cb06f))
+
+### Documentation
+
+- Update sandboxing and broker defaults
+  ([`9ac4dcc`](https://github.com/AnthusAI/Tactus/commit/9ac4dcc7f65b54ab1a516d190afc748c933ee6e8))
+
+### Features
+
+- Add default current directory volume mount
+  ([`095c687`](https://github.com/AnthusAI/Tactus/commit/095c687c3758c01c2c93929f929a2e00045e831b))
+
+
 ## v0.27.0 (2026-01-11)
 
 ### Features

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.27.0
+Version: 0.28.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
@@ -636,6 +636,22 @@ researcher({
 
 See `examples/14-feature-per-turn-tools.tac` for a complete working example.
 
+### Checkpointed Steps (Determinism)
+
+For durable execution, any operation that touches external state (randomness, time, APIs not in tools) must be checkpointed. Tactus provides `Step.checkpoint` for this:
+
+```lua
+-- Non-deterministic operation wrapped in checkpoint
+local data = Step.checkpoint(function()
+  return http_get("https://api.example.com/data")
+end)
+
+-- On replay, the function is NOT called again.
+-- The previously saved 'data' is returned immediately.
+```
+
+This ensures that when a procedure resumes after a pause (e.g. waiting for a human), it doesn't re-execute side effects or get different random values.
+
 ### File I/O Operations
 
 Tactus provides safe file I/O operations for reading and writing data files, with all operations restricted to the current working directory for security.
@@ -1085,6 +1101,60 @@ default_provider: openai
 default_model: gpt-4o
 ```
 
+### DSPy Integration
+
+Tactus provides first-class support for **DSPy Modules and Signatures**, enabling you to build declarative, self-optimizing AI components directly within your agent workflows.
+
+**Modules & Signatures:**
+
+Instead of hand-tuning prompts, define what you want the model to do using typed signatures:
+
+```lua
+-- Configure the Language Model for DSPy
+LM("openai/gpt-4o")
+
+-- Define a module with a typed signature
+summarizer = Module {
+  signature = "text -> summary",
+  strategy = "chain_of_thought"  -- Use Chain of Thought reasoning
+}
+
+-- Or define complex signatures with specific fields
+classifier = Module {
+  signature = Signature {
+    input = {
+      text = field.string{description = "The customer email to classify"}
+    },
+    output = {
+      category = field.string{description = "Support category (Billing, Tech, Sales)"},
+      priority = field.string{description = "Priority level (Low, High, Critical)"}
+    }
+  },
+  strategy = "predict"
+}
+```
+
+**Using Modules:**
+
+Modules are callable just like Agents or Tools:
+
+```lua
+Procedure {
+  function(input)
+    -- Call the module
+    local result = classifier({text = input.email})
+    
+    if result.priority == "Critical" then
+      human_escalation({context = result})
+    else
+      auto_responder({category = result.category})
+    end
+  end
+}
+```
+
+This brings the power of DSPy's programmable LLM interfaces into Tactus's durable, orchestrated environment.
+
 ### Asynchronous Execution
 
 Tactus is built on **async I/O** from the ground up, making it ideal for LLM-based workflows where you spend most of your time waiting for API responses.
@@ -1275,6 +1345,21 @@ Then reference them in your procedure:
 local approved = Human.approve("confirm_publish")
 ```
 
+**System Alerts:**
+
+Send alerts to your monitoring infrastructure (Datadog, PagerDuty) directly from the workflow:
+
+```lua
+System.alert({
+  message = "Failure rate exceeded threshold",
+  level = "error",  -- info, warning, error, critical
+  context = {
+    current_rate = 0.15,
+    threshold = 0.05
+  }
+})
+```
+
 ### Cost Tracking & Metrics
 
 Tactus provides **comprehensive cost and performance tracking** for all LLM calls. Every agent interaction is monitored with detailed metrics, giving you complete visibility into costs, performance, and behavior.
@@ -1360,20 +1445,37 @@ The AI agent space is crowded. This section explains how Tactus differs from alt
 
 ### DSPy
 
-[DSPy](https://dspy.ai) (Declarative Self-improving Python) treats prompting as a compilation target. You define typed signatures and let optimizers automatically discover effective prompts, few-shot examples, or fine-tuning strategies. DSPy excels at tasks where you have training data and clear metrics—classification, RAG, information extraction—and want to programmatically iterate on prompt quality without manual tuning.
+[DSPy](https://dspy.ai) (Declarative Self-improving Python) is the engine that powers Tactus's intelligence layer. Tactus integrates DSPy directly, allowing you to define DSPy Modules, Signatures, and Optimizers within your `.tac` files using a clean Lua syntax.
+
+While DSPy provides the primitives for programming with language models (optimizing prompts, few-shot examples, and reasoning steps), Tactus provides the **orchestration layer** that makes these components production-ready:
 
-Tactus takes a different approach: rather than optimizing prompts automatically, it provides a token-efficient, sandboxed language that serves as a safe platform for user-contributed or AI-generated code. Where DSPy hides control flow behind module composition, Tactus makes it explicit—you write the loops, conditionals, and error handling while agents handle intelligence within each turn.
+- **Durability**: Tactus handles checkpointing and resuming DSPy module calls transparently.
+- **Orchestration**: Tactus manages the control flow (loops, conditionals) around your DSPy modules.
+- **Human-in-the-Loop**: Tactus allows humans to inspect, approve, or correct DSPy module outputs.
+- **Sandboxing**: Tactus runs DSPy components in a safe, sandboxed environment suitable for user-contributed code.
+
+You can use Tactus to define standard DSPy modules:
+
+```lua
+-- Define a DSPy Module with a typed signature
+qa = Module {
+  signature = "question -> answer",
+  strategy = "chain_of_thought"
+}
+
+-- Invoke it as part of a durable workflow
+local result = qa({question = "How does this work?"})
+```
 
-The frameworks are complementary: you could use DSPy to optimize the prompts that go into a Tactus agent's `system_prompt`, then use Tactus to orchestrate those optimized agents in a durable, human-in-the-loop workflow.
+Tactus and DSPy work together: DSPy handles the *thinking* (optimizing how to get the best answer), while Tactus handles the *doing* (ensuring the workflow completes reliably, even if it takes days).
 
-| | DSPy | Tactus |
-|-|------|--------|
-| **Core idea** | Programming, not prompting | Token-efficient, AI-manipulable orchestration language |
-| **Optimization** | Automatic (optimizers) | Manual or agent-driven self-evolution |
-| **Control flow** | Declarative composition | Imperative Lua DSL |
-| **Human-in-the-loop** | Not built-in | First-class citizen |
-| **Durability** | Caching | Checkpointing + replay |
-| **Target** | Researchers optimizing prompts | Engineers building production workflows |
+| | DSPy (Python) | Tactus (Lua) |
+|---|---|---|
+| **Role** | Intelligence Engine | Orchestration Engine |
+| **Focus** | Prompt optimization, reasoning | Durability, HITL, Sandboxing |
+| **Definition** | Python classes | Lua DSL primitives |
+| **State** | In-memory | Persisted & Resumable |
+| **Optimization** | Automatic (Teleprompters) | Agent-driven or Manual |
 
 ### LangGraph
 
@@ -1409,17 +1511,18 @@ The major AI companies have released their own agent frameworks:
 
 - **[Meta Llama Stack](https://ai.meta.com/blog/meta-llama-3-1/)** — Standardized interfaces for building agentic applications with Llama models. More of an API specification than a workflow framework.
 
-These frameworks are valuable if you're committed to a specific vendor's ecosystem. Tactus is model-agnostic (via Pydantic-AI) and designed to run anywhere—local, cloud, or AWS Lambda Durable Functions.
+These frameworks are valuable if you're committed to a specific vendor's ecosystem. Tactus is model-agnostic (via [DSPy](https://dspy.ai)) and designed to run anywhere—local, cloud, or AWS Lambda Durable Functions.
 
 ### Other Tools
 
-- **[Pydantic-AI](https://github.com/pydantic/pydantic-ai)** — Type-safe LLM integration that Tactus uses under the hood. Tactus adds orchestration, HITL, and durability on top.
+- **[Pydantic-AI](https://github.com/pydantic/pydantic-ai)** — Used for type-safe tool definitions and message structures.
 
 - **[Guidance](https://github.com/guidance-ai/guidance)** (Microsoft) — Interleaves constrained generation with control flow. Focuses on token-level control during generation rather than workflow orchestration.
 
 ## Complete Feature List
 
 - **Durable Execution**: Automatic position-based checkpointing for all operations (agent turns, model predictions, sub-procedure calls, HITL interactions) with replay-based recovery—resume from exactly where you left off after crashes, timeouts, or pauses
+- **DSPy Integration**: First-class support for DSPy Modules and Signatures, enabling declarative machine learning components and prompt optimization alongside agentic workflows
 - **Model Primitive**: First-class support for ML inference (PyTorch, HTTP, HuggingFace Transformers) with automatic checkpointing—distinct from conversational agents for classification, prediction, and transformation tasks
 - **Script Mode**: Write procedures without explicit `main` definitions—top-level `input`/`output` declarations and code automatically wrapped as the main procedure
 - **State Management**: Typed, schema-validated persistent state with automatic initialization from defaults and runtime validation
@@ -1434,7 +1537,7 @@ These frameworks are valuable if you're committed to a specific vendor's ecosyst
 - **Context Engineering**: Fine-grained control over conversation history per agent
 - **Typed Input/Output**: JSON Schema validation with UI generation support using `input`/`output`/`state` declarations
 - **Pluggable Backends**: Storage, HITL, and chat recording via Pydantic protocols
-- **LLM Integration**: Works with OpenAI and Bedrock via [pydantic-ai](https://github.com/pydantic/pydantic-ai)
+- **LLM Integration**: Works with OpenAI and Bedrock via [DSPy](https://dspy.ai)
 - **Standalone CLI**: Run workflows without any infrastructure
 - **Type-Safe**: Pydantic models throughout for validation and type safety
 

{tactus-0.27.0 → tactus-0.28.0}/README.md

@@ -585,6 +585,22 @@ researcher({
 
 See `examples/14-feature-per-turn-tools.tac` for a complete working example.
 
+### Checkpointed Steps (Determinism)
+
+For durable execution, any operation that touches external state (randomness, time, APIs not in tools) must be checkpointed. Tactus provides `Step.checkpoint` for this:
+
+```lua
+-- Non-deterministic operation wrapped in checkpoint
+local data = Step.checkpoint(function()
+  return http_get("https://api.example.com/data")
+end)
+
+-- On replay, the function is NOT called again.
+-- The previously saved 'data' is returned immediately.
+```
+
+This ensures that when a procedure resumes after a pause (e.g. waiting for a human), it doesn't re-execute side effects or get different random values.
+
 ### File I/O Operations
 
 Tactus provides safe file I/O operations for reading and writing data files, with all operations restricted to the current working directory for security.
@@ -1034,6 +1050,60 @@ default_provider: openai
 default_model: gpt-4o
 ```
 
+### DSPy Integration
+
+Tactus provides first-class support for **DSPy Modules and Signatures**, enabling you to build declarative, self-optimizing AI components directly within your agent workflows.
+
+**Modules & Signatures:**
+
+Instead of hand-tuning prompts, define what you want the model to do using typed signatures:
+
+```lua
+-- Configure the Language Model for DSPy
+LM("openai/gpt-4o")
+
+-- Define a module with a typed signature
+summarizer = Module {
+  signature = "text -> summary",
+  strategy = "chain_of_thought"  -- Use Chain of Thought reasoning
+}
+
+-- Or define complex signatures with specific fields
+classifier = Module {
+  signature = Signature {
+    input = {
+      text = field.string{description = "The customer email to classify"}
+    },
+    output = {
+      category = field.string{description = "Support category (Billing, Tech, Sales)"},
+      priority = field.string{description = "Priority level (Low, High, Critical)"}
+    }
+  },
+  strategy = "predict"
+}
+```
+
+**Using Modules:**
+
+Modules are callable just like Agents or Tools:
+
+```lua
+Procedure {
+  function(input)
+    -- Call the module
+    local result = classifier({text = input.email})
+    
+    if result.priority == "Critical" then
+      human_escalation({context = result})
+    else
+      auto_responder({category = result.category})
+    end
+  end
+}
+```
+
+This brings the power of DSPy's programmable LLM interfaces into Tactus's durable, orchestrated environment.
+
 ### Asynchronous Execution
 
 Tactus is built on **async I/O** from the ground up, making it ideal for LLM-based workflows where you spend most of your time waiting for API responses.
@@ -1224,6 +1294,21 @@ Then reference them in your procedure:
 local approved = Human.approve("confirm_publish")
 ```
 
+**System Alerts:**
+
+Send alerts to your monitoring infrastructure (Datadog, PagerDuty) directly from the workflow:
+
+```lua
+System.alert({
+  message = "Failure rate exceeded threshold",
+  level = "error",  -- info, warning, error, critical
+  context = {
+    current_rate = 0.15,
+    threshold = 0.05
+  }
+})
+```
+
 ### Cost Tracking & Metrics
 
 Tactus provides **comprehensive cost and performance tracking** for all LLM calls. Every agent interaction is monitored with detailed metrics, giving you complete visibility into costs, performance, and behavior.
@@ -1309,20 +1394,37 @@ The AI agent space is crowded. This section explains how Tactus differs from alt
 
 ### DSPy
 
-[DSPy](https://dspy.ai) (Declarative Self-improving Python) treats prompting as a compilation target. You define typed signatures and let optimizers automatically discover effective prompts, few-shot examples, or fine-tuning strategies. DSPy excels at tasks where you have training data and clear metrics—classification, RAG, information extraction—and want to programmatically iterate on prompt quality without manual tuning.
+[DSPy](https://dspy.ai) (Declarative Self-improving Python) is the engine that powers Tactus's intelligence layer. Tactus integrates DSPy directly, allowing you to define DSPy Modules, Signatures, and Optimizers within your `.tac` files using a clean Lua syntax.
+
+While DSPy provides the primitives for programming with language models (optimizing prompts, few-shot examples, and reasoning steps), Tactus provides the **orchestration layer** that makes these components production-ready:
 
-Tactus takes a different approach: rather than optimizing prompts automatically, it provides a token-efficient, sandboxed language that serves as a safe platform for user-contributed or AI-generated code. Where DSPy hides control flow behind module composition, Tactus makes it explicit—you write the loops, conditionals, and error handling while agents handle intelligence within each turn.
+- **Durability**: Tactus handles checkpointing and resuming DSPy module calls transparently.
+- **Orchestration**: Tactus manages the control flow (loops, conditionals) around your DSPy modules.
+- **Human-in-the-Loop**: Tactus allows humans to inspect, approve, or correct DSPy module outputs.
+- **Sandboxing**: Tactus runs DSPy components in a safe, sandboxed environment suitable for user-contributed code.
+
+You can use Tactus to define standard DSPy modules:
+
+```lua
+-- Define a DSPy Module with a typed signature
+qa = Module {
+  signature = "question -> answer",
+  strategy = "chain_of_thought"
+}
+
+-- Invoke it as part of a durable workflow
+local result = qa({question = "How does this work?"})
+```
 
-The frameworks are complementary: you could use DSPy to optimize the prompts that go into a Tactus agent's `system_prompt`, then use Tactus to orchestrate those optimized agents in a durable, human-in-the-loop workflow.
+Tactus and DSPy work together: DSPy handles the *thinking* (optimizing how to get the best answer), while Tactus handles the *doing* (ensuring the workflow completes reliably, even if it takes days).
 
-| | DSPy | Tactus |
-|-|------|--------|
-| **Core idea** | Programming, not prompting | Token-efficient, AI-manipulable orchestration language |
-| **Optimization** | Automatic (optimizers) | Manual or agent-driven self-evolution |
-| **Control flow** | Declarative composition | Imperative Lua DSL |
-| **Human-in-the-loop** | Not built-in | First-class citizen |
-| **Durability** | Caching | Checkpointing + replay |
-| **Target** | Researchers optimizing prompts | Engineers building production workflows |
+| | DSPy (Python) | Tactus (Lua) |
+|---|---|---|
+| **Role** | Intelligence Engine | Orchestration Engine |
+| **Focus** | Prompt optimization, reasoning | Durability, HITL, Sandboxing |
+| **Definition** | Python classes | Lua DSL primitives |
+| **State** | In-memory | Persisted & Resumable |
+| **Optimization** | Automatic (Teleprompters) | Agent-driven or Manual |
 
 ### LangGraph
 
@@ -1358,17 +1460,18 @@ The major AI companies have released their own agent frameworks:
 
 - **[Meta Llama Stack](https://ai.meta.com/blog/meta-llama-3-1/)** — Standardized interfaces for building agentic applications with Llama models. More of an API specification than a workflow framework.
 
-These frameworks are valuable if you're committed to a specific vendor's ecosystem. Tactus is model-agnostic (via Pydantic-AI) and designed to run anywhere—local, cloud, or AWS Lambda Durable Functions.
+These frameworks are valuable if you're committed to a specific vendor's ecosystem. Tactus is model-agnostic (via [DSPy](https://dspy.ai)) and designed to run anywhere—local, cloud, or AWS Lambda Durable Functions.
 
 ### Other Tools
 
-- **[Pydantic-AI](https://github.com/pydantic/pydantic-ai)** — Type-safe LLM integration that Tactus uses under the hood. Tactus adds orchestration, HITL, and durability on top.
+- **[Pydantic-AI](https://github.com/pydantic/pydantic-ai)** — Used for type-safe tool definitions and message structures.
 
 - **[Guidance](https://github.com/guidance-ai/guidance)** (Microsoft) — Interleaves constrained generation with control flow. Focuses on token-level control during generation rather than workflow orchestration.
 
 ## Complete Feature List
 
 - **Durable Execution**: Automatic position-based checkpointing for all operations (agent turns, model predictions, sub-procedure calls, HITL interactions) with replay-based recovery—resume from exactly where you left off after crashes, timeouts, or pauses
+- **DSPy Integration**: First-class support for DSPy Modules and Signatures, enabling declarative machine learning components and prompt optimization alongside agentic workflows
 - **Model Primitive**: First-class support for ML inference (PyTorch, HTTP, HuggingFace Transformers) with automatic checkpointing—distinct from conversational agents for classification, prediction, and transformation tasks
 - **Script Mode**: Write procedures without explicit `main` definitions—top-level `input`/`output` declarations and code automatically wrapped as the main procedure
 - **State Management**: Typed, schema-validated persistent state with automatic initialization from defaults and runtime validation
@@ -1383,7 +1486,7 @@ These frameworks are valuable if you're committed to a specific vendor's ecosyst
 - **Context Engineering**: Fine-grained control over conversation history per agent
 - **Typed Input/Output**: JSON Schema validation with UI generation support using `input`/`output`/`state` declarations
 - **Pluggable Backends**: Storage, HITL, and chat recording via Pydantic protocols
-- **LLM Integration**: Works with OpenAI and Bedrock via [pydantic-ai](https://github.com/pydantic/pydantic-ai)
+- **LLM Integration**: Works with OpenAI and Bedrock via [DSPy](https://dspy.ai)
 - **Standalone CLI**: Run workflows without any infrastructure
 - **Type-Safe**: Pydantic models throughout for validation and type safety
 

{tactus-0.27.0 → tactus-0.28.0}/docs/CONFIGURATION.md

@@ -131,32 +131,69 @@ Control network access for procedures:
 
 ```yaml
 sandbox:
-  network: "bridge"  # Network mode (default: bridge)
+  network: "none"  # Network mode (default: none)
 
   # Options:
   # - "bridge": Default Docker bridge (allows outbound connections)
-  # - "none": No network access (most secure, but can't call LLM APIs)
+  # - "none": No network access in the runtime container (most secure)
   # - "host": Use host network (not recommended for security)
   # - "custom-network": Use a custom Docker network
 ```
 
-**Security consideration**: Default `bridge` mode allows outbound connections (needed for LLM API calls), but agents could potentially exfiltrate data. See [Sandboxing Guide: Threat Model](./SANDBOXING.md#threat-model) for details.
+With the brokered sandbox runtime, `network: none` can still support LLM calls because the runtime talks to a host-side broker over the configured broker transport (default: `stdio`).
+
+If you enable runtime networking (`network != none`), treat that as higher risk and enforce egress controls so the runtime can only reach the broker. See [Sandboxing Guide: Threat Model](./SANDBOXING.md#threat-model).
+
+### Broker Transport
+
+Control how the secretless runtime container communicates with the host broker:
+
+```yaml
+sandbox:
+  broker_transport: "stdio"  # default (works with network: none)
+```
+
+Options:
+- `stdio`: Local Docker MVP; container stays networkless and communicates via the docker attach stdio channel
+- `tcp`: Remote-style connectivity; requires `sandbox.network != none`
+- `tls`: Same as `tcp` but wrapped in TLS; requires `sandbox.network != none`
 
 ### Volume Mounts
 
-Mount host directories into the container:
+**Default behavior**: Tactus automatically mounts your current directory to `/workspace:rw`, making it easy for procedures to read and write project files. This is safe because:
+- Container isolation prevents access outside the mounted directory
+- Git provides version control and rollback capability
+- You can review all changes before committing
+
+To disable the default mount:
+
+```yaml
+sandbox:
+  mount_current_dir: false  # Disable automatic current directory mount
+```
+
+**Additional volume mounts**: Mount other host directories into the container:
 
 ```yaml
 sandbox:
   volumes:
     - "/host/data:/data:ro"           # Read-only mount
     - "/host/outputs:/outputs:rw"     # Read-write mount
-    - "/shared/config:/config:ro"
+    - "../other-repo:/external:ro"    # Relative paths supported
 ```
 
+**Path resolution**:
+- Relative paths (e.g., `./data`, `../repo`) resolve from the procedure directory
+- `~` expands to your home directory
+- Absolute paths used as-is
+
+**Volume modes**:
+- `:ro` - Read-only (safer when you don't need writes)
+- `:rw` - Read-write (default if not specified)
+
 **Default mounts** (always included):
-- Workspace: Temporary directory at `/workspace` (ephemeral, destroyed after run)
-- MCP Servers: `~/.tactus/mcp-servers` at `/mcp-servers` (read-only)
+- Current directory: `.:/workspace:rw` (unless `mount_current_dir: false`)
+- MCP Servers: `~/.tactus/mcp-servers` at `/mcp-servers` (read-only, if exists)
 
 ### Environment Variables
 
@@ -170,10 +207,7 @@ sandbox:
     LOG_LEVEL: "info"
 ```
 
-**Automatically passed through** (no configuration needed):
-- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`
-- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_SESSION_TOKEN`
-- `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`
+Tactus intentionally blocks common secret env vars from entering the runtime container. For LLM calls, provide credentials to the host/broker side (for example via your shell environment or host-side config loading), not via `sandbox.env`.
 
 ### Per-Procedure Sandbox Configuration