tactus 0.29.4__tar.gz → 0.31.0__tar.gz

{tactus-0.29.4 → tactus-0.31.0}/AGENTS.md

@@ -376,6 +376,10 @@ Tactus has two distinct testing mechanisms that serve different purposes:
 
 The Tactus CLI provides powerful tools for developing and debugging agents.
 
+### Formatting `.tac` Files
+
+Use `tactus format` to automatically reindent and normalize whitespace in `.tac` files.
+
 ### Running and Debugging Procedures
 
 When you run a procedure with `tactus run`, you get real-time visibility into what's happening:

{tactus-0.29.4 → tactus-0.31.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 <!-- version list -->
 
+## v0.31.0 (2026-01-15)
+
+### Chores
+
+- Merge origin/main
+  ([`dd8c4d4`](https://github.com/AnthusAI/Tactus/commit/dd8c4d4aa08cf4d7aaf8be69e76309a66be36ec8))
+
+### Documentation
+
+- Add workaround for macOS Gatekeeper damaged app error
+  ([`cbf9b38`](https://github.com/AnthusAI/Tactus/commit/cbf9b38a25a99d8f0ff8949e3a646ed69d276713))
+
+
+## v0.30.0 (2026-01-15)
+
+
 ## v0.29.4 (2026-01-15)
 
 ### Bug Fixes

{tactus-0.29.4 → tactus-0.31.0}/IMPLEMENTATION.md

@@ -993,24 +993,6 @@ On replay, completed sub-procedure calls return cached results without re-execut
 - DSL Stub: `tactus/core/dsl_stubs.py` (`_procedure` function)
 - Registry: `tactus/core/registry.py`
 
-### Stages
-
-#### StagePrimitive (`tactus/primitives/stage.py`)
-
-**Status**: ✅ **Fully Implemented**
-
-**Features:**
-- ✅ `Stage.set(name)` - Set current stage
-- ✅ `Stage.current()` - Get current stage
-- ✅ `Stage.advance()` - Move to next stage in sequence
-- ✅ `Stage.is(name)` - Check if in specific stage (mapped from Lua `is` keyword)
-- ✅ `Stage.history()` - Get transition history
-
-**Implementation:**
-- Validates stage names against `stages:` declaration in YAML
-- Tracks stage transitions with timestamps
-- Returns history as Lua table
-
 ### Exception Handling
 
 **Specification**: Supports `pcall()` for protected calls.
@@ -1300,10 +1282,6 @@ procedure "order_fulfillment" {
 
 **Location**: `tactus/primitives/state.py`
 
-#### Stage Primitives
-
-**Status**: ✅ **Fully Implemented** (see Stages section above)
-
 #### Control Primitives
 
 #### IterationsPrimitive (`tactus/primitives/control.py`)
@@ -1669,7 +1647,6 @@ Defines interface for persistence.
 
 **Built-in Steps:**
 - Tool steps: `the {tool} tool should be called`, `at least {n} times`, `with {param}={value}`
-- Stage steps: `the stage should be {stage}`, `transition from {s1} to {s2}`
 - State steps: `the state {key} should be {value}`, `should exist`
 - Completion steps: `should complete successfully`, `stop reason should contain {text}`
 - Iteration steps: `iterations should be less than {n}`, `between {min} and {max}`
@@ -1816,7 +1793,6 @@ tactus/
 │   ├── tool.py                 # ToolPrimitive
 │   ├── human.py                # HumanPrimitive (HITL)
 │   ├── step.py                 # StepPrimitive, checkpoint() function
-│   ├── stage.py                # StagePrimitive
 │   ├── control.py              # IterationsPrimitive, StopPrimitive
 │   ├── log.py                  # LogPrimitive
 │   ├── json.py                 # JsonPrimitive

{tactus-0.29.4 → tactus-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tactus
-Version: 0.29.4
+Version: 0.31.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
@@ -170,7 +170,7 @@ Procedure {
   end
 }
 
-Specifications([[
+Specification([[
 Feature: Research
   Scenario: Completes research
     When the researcher agent takes turns
@@ -421,12 +421,12 @@ calculator = Agent {
 done = tactus.done
 
 text_processor = Agent {
-  tools = {
-    done,
+  inline_tools = {
     {name = "uppercase", input = {...}, handler = function(args)
       return string.upper(args.text)
     end}
-  }
+  },
+  tools = {done}
 }
 ```
 
@@ -533,7 +533,7 @@ Procedure {
   end
 }
 
-Specifications([[
+Specification([[
 Feature: Greeting
   Scenario: Agent greets and completes
     When the greeter agent takes turns
@@ -616,7 +616,7 @@ This creates a rhythm: **tool call → summarization → tool call → summariza
 
 **Why this matters:**
 
-Without per-call control, an agent might call another tool when you just want it to explain the previous result. By temporarily restricting tools to an empty set (`tools = {}`), you ensure the agent focuses on summarization.
+Without per-call control, an agent might call another tool when you just want it to explain the previous result. By temporarily restricting toolsets to an empty set (`tools = {}`), you ensure the agent focuses on summarization.
 
 **Other per-call overrides:**
 
@@ -731,10 +731,9 @@ Then the search tool should be called exactly 2 times
 Then the search tool should be called with query=test
 ```
 
-**State & Stage Steps:**
+**State Steps:**
 ```gherkin
 Given the procedure has started
-Then the stage should be processing
 Then the state count should be 5
 Then the state error should exist
 ```
@@ -866,10 +865,9 @@ Then the search tool should be called exactly 2 times
 Then the search tool should be called with query=test
 ```
 
-**State & Stage Steps:**
+**State Steps:**
 ```gherkin
 Given the procedure has started
-Then the stage should be processing
 Then the state count should be 5
 Then the state error should exist
 ```
@@ -1665,6 +1663,12 @@ Agents:
 # Validate syntax and structure
 tactus validate workflow.tac
 
+# Format a workflow file (2-space indentation + normalized spacing)
+tactus format workflow.tac
+
+# Check formatting without rewriting (exit 1 if changes needed)
+tactus format workflow.tac --check
+
 # Run BDD specifications
 tactus test workflow.tac
 
@@ -1675,6 +1679,8 @@ tactus test workflow.tac --runs 10
 tactus eval workflow.tac --runs 10
 ```
 
+The `format` command uses Tactus's Lua parser to reindent and normalize whitespace while preserving the structure of the code.
+
 ### Understanding Output
 
 The CLI displays several types of events:

{tactus-0.29.4 → tactus-0.31.0}/README.md

@@ -119,7 +119,7 @@ Procedure {
   end
 }
 
-Specifications([[
+Specification([[
 Feature: Research
   Scenario: Completes research
     When the researcher agent takes turns
@@ -370,12 +370,12 @@ calculator = Agent {
 done = tactus.done
 
 text_processor = Agent {
-  tools = {
-    done,
+  inline_tools = {
     {name = "uppercase", input = {...}, handler = function(args)
       return string.upper(args.text)
     end}
-  }
+  },
+  tools = {done}
 }
 ```
 
@@ -482,7 +482,7 @@ Procedure {
   end
 }
 
-Specifications([[
+Specification([[
 Feature: Greeting
   Scenario: Agent greets and completes
     When the greeter agent takes turns
@@ -565,7 +565,7 @@ This creates a rhythm: **tool call → summarization → tool call → summariza
 
 **Why this matters:**
 
-Without per-call control, an agent might call another tool when you just want it to explain the previous result. By temporarily restricting tools to an empty set (`tools = {}`), you ensure the agent focuses on summarization.
+Without per-call control, an agent might call another tool when you just want it to explain the previous result. By temporarily restricting toolsets to an empty set (`tools = {}`), you ensure the agent focuses on summarization.
 
 **Other per-call overrides:**
 
@@ -680,10 +680,9 @@ Then the search tool should be called exactly 2 times
 Then the search tool should be called with query=test
 ```
 
-**State & Stage Steps:**
+**State Steps:**
 ```gherkin
 Given the procedure has started
-Then the stage should be processing
 Then the state count should be 5
 Then the state error should exist
 ```
@@ -815,10 +814,9 @@ Then the search tool should be called exactly 2 times
 Then the search tool should be called with query=test
 ```
 
-**State & Stage Steps:**
+**State Steps:**
 ```gherkin
 Given the procedure has started
-Then the stage should be processing
 Then the state count should be 5
 Then the state error should exist
 ```
@@ -1614,6 +1612,12 @@ Agents:
 # Validate syntax and structure
 tactus validate workflow.tac
 
+# Format a workflow file (2-space indentation + normalized spacing)
+tactus format workflow.tac
+
+# Check formatting without rewriting (exit 1 if changes needed)
+tactus format workflow.tac --check
+
 # Run BDD specifications
 tactus test workflow.tac
 
@@ -1624,6 +1628,8 @@ tactus test workflow.tac --runs 10
 tactus eval workflow.tac --runs 10
 ```
 
+The `format` command uses Tactus's Lua parser to reindent and normalize whitespace while preserving the structure of the code.
+
 ### Understanding Output
 
 The CLI displays several types of events:

{tactus-0.29.4 → tactus-0.31.0}/SPECIFICATION.md

@@ -47,9 +47,6 @@ worker = Agent {
     tools = {done}  -- Variable references, not strings
 }
 
--- Stages (optional)
-Stages({"planning", "executing", "complete"})
-
 -- Procedure (unnamed, defaults to "main")
 Procedure {
     -- Input (using field builder syntax)
@@ -83,7 +80,7 @@ Procedure {
 }
 
 -- BDD Specifications (optional)
-Specifications([[
+Specification([[
 Feature: Task Processing
   Scenario: Task completes successfully
     Given the procedure has started
@@ -95,12 +92,12 @@ Feature: Task Processing
 
 **Key structure:**
 - **Tools** defined as `name = Tool {...}` or imported via `require()` like `local done = require("tactus.tools.done")`
-- **Agents** defined as `name = Agent {...}` with `tools = {var1, var2}` or `toolsets = {"tool_name"}`
+- **Agents** defined as `name = Agent {...}` with `tools = {...}`; `tools = {...}` is reserved for inline tool definitions only
 - **Procedure { }** unnamed, defaults to "main"
   - Config fields: `input`, `output`, `state` (state is optional)
   - Function as the last element containing the procedure logic
 - **Agent calls** use callable syntax: `worker()` or `worker({message = "..."})`
-- **Specifications()** at top level for BDD tests
+- **Specification()** / **Specifications()** at top level for BDD tests
 
 ---
 
@@ -292,7 +289,7 @@ researcher = Agent {
     provider = "openai",
     model = "gpt-4o",
     system_prompt = "Research the topic",
-    toolsets = {"brave_search", "done"},  -- MCP tools referenced by name
+    tools = {"brave_search", "done"},  -- MCP tools referenced by name
 
     message_history = {
         source = "shared",  -- Use shared history
@@ -1122,34 +1119,6 @@ local result = Human.approve({
 -- If on_timeout = "error", throws exception on timeout
 ```
 
-### HITL Stage Integration
-
-When a procedure is waiting for human interaction, its stage reflects this:
-
-```lua
-Stage.set("processing")
-do_work()
-
--- Procedure status becomes "waiting_for_human" during this call
-local approved = Human.approve({message = "Continue?"})
-
-Stage.set("finalizing")
-```
-
-Parent procedures can detect this:
-
-```lua
-local handle = Procedure.spawn("deployment", params)
-
-local status = Procedure.status(handle)
-if status.waiting_for_human then
-  -- Maybe notify via Slack
-  notify_channel("Deployment waiting for approval")
-end
-```
-
----
-
 ## Human-AI Chat (Non-Procedural)
 
 The same `ChatSession` and `ChatMessage` infrastructure supports regular conversational AI assistants that aren't running procedure workflows.
@@ -1327,8 +1296,7 @@ The runtime detects script mode during execution and performs source transformat
 - `input {}`
 - `output {}`
 - `Mocks {}`
-- `Stages()`
-- `Specifications()`
+- `Specification()` / `Specifications()`
 - Agent definitions: `name = Agent {}`
 - Tool definitions: `name = Tool {}` or imported via `require()` like `local done = require("tactus.tools.done")`
 - Model definitions: `name = Model {}`
@@ -1460,7 +1428,7 @@ Context: {prepared.data}
 
     initial_message = "Begin working on the task.",
 
-    toolsets = {"brave_search_search", "done"},  -- MCP tools referenced by string name
+    tools = {"brave_search_search", "done"},  -- MCP tools referenced by string name
 
     filter = {
         class = "ComposedFilter",
@@ -1995,8 +1963,7 @@ local done = require("tactus.tools.done")
 text_processor = Agent {
     provider = "openai",
     system_prompt = "You process text",
-    tools = {
-        done,
+    inline_tools = {
         {
             name = "uppercase",
             description = "Convert text to uppercase",
@@ -2017,7 +1984,8 @@ text_processor = Agent {
                 return string.reverse(args.text)
             end
         }
-    }
+    },
+    tools = {done}
 }
 ```
 
@@ -2025,10 +1993,9 @@ Inline tools are automatically prefixed with the agent name (e.g., `text_process
 
 **Tools in Agent Config**
 
-In agent configuration, `tools` accepts:
-- **Variable references** to tools: `done`, `calculate_tip`
-- **Variable references** to toolsets: `math_tools`
-- **Inline tool definitions** (objects with `name`, `handler`, `input`)
+In agent configuration:
+- `tools` accepts **tool/toolset references** and toolset expressions.
+- `inline_tools` is reserved for **inline tool definitions** (objects with `name`, `handler`, `input`).
 
 ```lua
 local done = require("tactus.tools.done")
@@ -2036,11 +2003,13 @@ calculate_tip = Tool {...}
 math_tools = Toolset {...}
 
 example = Agent {
-    tools = {
-        done,           -- Variable reference to tool
-        calculate_tip,  -- Variable reference to tool
-        math_tools,     -- Variable reference to toolset
+    inline_tools = {
         {name = "my_tool", handler = function(args) ... end, ...}  -- Inline
+    },
+    tools = {
+        done,           -- Tool reference
+        calculate_tip,  -- Tool reference
+        math_tools,     -- Toolset reference
     }
 }
 ```
@@ -2156,35 +2125,6 @@ local status = handle.status()
 local result = handle.wait()
 ```
 
----
-
-## Stages
-
-Stages integrate with TaskStages monitoring:
-
-```lua
--- Define stages at top level
-Stages({"planning", "executing", "awaiting_human", "complete"})
-
--- Use in procedure
-Procedure {
-    function(input)
-        Stage.set("planning")
-        -- Do planning work...
-
-        Stage.advance("executing")
-        -- Execute tasks...
-
-        Stage.is("planning")  -- false
-        Stage.current()       -- "executing"
-
-        -- Continue with rest of procedure...
-    end
-}
-```
-
----
-
 ## Exception Handling
 
 ```lua
@@ -2298,15 +2238,15 @@ response.tool_calls
 The callable agent accepts an optional table to override behavior for a single call:
 
 **Available overrides:**
-- `message` (string) - Message to send to the agent (mapped to inject internally)
+- `message` (string) - Message to send to the agent
 - `context` (table) - Key-value pairs to pass as context to the agent (formatted as structured input)
-- `tools` (list of variables) - Tool and toolset variables available for this call (empty list = no tools)
+- `tools` (list of toolset expressions) - Tools/toolsets available for this call (empty list = no tools)
 - `temperature` (number) - Override temperature for this call
 - `max_tokens` (number) - Override max_tokens for this call
 - `top_p` (number) - Override top_p for this call
 
 **Tool Override Behavior:**
-- `tools` - List of tool/toolset variables to enable: `{search, done, math_tools}`
+- `tools` - List of tool/toolset references to enable: `{search, done, math_tools}`
 - Empty list `{}`: No tools available for this call
 - `nil`/omitted: Use agent's default configuration
 
@@ -2406,16 +2346,6 @@ State.append("list", item)       -- Append to a list
 State.all()                      -- Get all state as table
 ```
 
-### Stage Primitives
-
-```lua
-Stage.current()
-Stage.set(name)
-Stage.advance(name)
-Stage.is(name)
-Stage.history()
-```
-
 ### Control Primitives
 
 ```lua
@@ -2534,7 +2464,7 @@ end
 Matchers are primarily used in BDD specifications for testing:
 
 ```lua
-Specifications([[
+Specification([[
 Feature: Data Processing
   Scenario: Process valid data
     Given the procedure has started
@@ -2556,9 +2486,9 @@ local error_matcher = contains("error")
 
 -- Use in conditional logic
 local result = worker()
-if tostring(result.value):find("success") then
+if tostring(result.output):find("success") then
     -- Contains success
-elseif tostring(result.value):find("error") then
+elseif tostring(result.output):find("error") then
     -- Contains error
 end
 ```
@@ -2586,9 +2516,6 @@ end
 ## Example: HITL Workflow
 
 ```lua
--- Define stages at top level
-Stages({"researching", "writing", "review", "publishing", "complete"})
-
 -- Define tools
 local done = require("tactus.tools.done")
 research = Tool {
@@ -2654,14 +2581,12 @@ Procedure {
     },
 
     function(input)
-        Stage.set("researching")
         Human.notify({
             message = "Starting content generation",
             level = "info",
             context = {topic = input.topic, target = input.target}
         })
 
-        Stage.set("writing")
         repeat
             writer()
         until done.called() or Iterations.exceeded(20)
@@ -2671,7 +2596,6 @@ Procedure {
         end
 
         -- Human review
-        Stage.set("review")
         local review = Human.review("review_content", {
             artifact = state.draft,
             artifact_type = "document"
@@ -2693,7 +2617,6 @@ Procedure {
         local final_content = review.edited_artifact or state.draft
 
         -- Approval to publish
-        Stage.set("publishing")
         local approved = Human.approve("confirm_publish")
 
         if not approved then
@@ -2710,7 +2633,6 @@ Procedure {
             context = {url = url}
         })
 
-        Stage.set("complete")
         return {published = true, url = url}
     end
 }
@@ -2721,9 +2643,6 @@ Procedure {
 ## Example: System Monitoring with Alerts
 
 ```lua
--- Define stages at top level
-Stages({"processing", "complete"})
-
 -- Main procedure
 Procedure {
     input = {
@@ -2741,8 +2660,6 @@ Procedure {
         local failed = 0
         local total = #input.items
 
-        Stage.set("processing")
-
         for i, item in ipairs(input.items) do
             local ok, result = pcall(process_item, item)
 
@@ -2789,8 +2706,6 @@ Procedure {
             end
         end
 
-        Stage.set("complete")
-
         -- Final status
         local level = failed > 0 and "warning" or "info"
         Human.notify({
@@ -2821,8 +2736,6 @@ A comprehensive example showing HITL with checkpointed tool calls, evaluation, a
 -- Note: This is a complex example showing multiple advanced features
 
 -- Define stages
-Stages({"analyzing", "drafting", "evaluating", "awaiting_approval", "promoting", "complete"})
-
 -- Import completion tool from standard library
 local done = require("tactus.tools.done")
 
@@ -2837,7 +2750,7 @@ Score ID: {input.score_id}
 Champion metrics: {state.champion_metrics}
 Error patterns: {state.error_analysis}
     ]],
-    toolsets = {"plexus_get_score", "plexus_get_evaluation_metrics", "plexus_analyze_errors", "done"},
+    tools = {"plexus_get_score", "plexus_get_evaluation_metrics", "plexus_analyze_errors", "done"},
     max_turns = 20
 }
 
@@ -2851,7 +2764,7 @@ Human feedback (if any): {state.human_feedback}
 
 Be conservative - small targeted improvements are better than sweeping changes.
     ]],
-    toolsets = {"plexus_draft_score_config", "plexus_validate_config", "done"},
+    tools = {"plexus_draft_score_config", "plexus_validate_config", "done"},
     max_turns = 15
 }
 
@@ -2889,7 +2802,6 @@ Procedure {
         local attempt = 1
 
         -- Evaluate champion FIRST (checkpointed, runs once)
-        Stage.set("analyzing")
 
         state.champion_config = Step.checkpoint(function()
             return plexus_get_score.run({score_id = input.score_id})
@@ -2922,7 +2834,6 @@ Procedure {
             state.analysis_findings = done.last_result()
 
             -- Draft improved configuration
-            Stage.set("drafting")
 
             repeat
                 drafter()
@@ -2936,7 +2847,6 @@ Procedure {
             state.candidate_config = candidate_config
 
             -- Evaluate candidate (checkpointed per attempt)
-            Stage.set("evaluating")
 
             local eval_result = Step.checkpoint(function()
                 return plexus_run_evaluation.run({
@@ -2972,7 +2882,6 @@ Procedure {
                 end
             else
                 -- Request human approval
-                Stage.set("awaiting_approval")
 
                 local review = Human.review("approval_to_promote", {
                     artifact = {
@@ -2985,8 +2894,6 @@ Procedure {
                 })
 
                 if review.decision == "Approve" then
-                    Stage.set("promoting")
-
                     local result = Step.checkpoint(function()
                         return plexus_promote_score_version.run({
                             score_id = input.score_id,
@@ -3000,7 +2907,6 @@ Procedure {
                         context = {version_id = result.version_id}
                     })
 
-                    Stage.set("complete")
                     return {
                         promoted = true,
                         new_version_id = result.version_id,
@@ -3015,7 +2921,6 @@ Procedure {
                     attempt = attempt + 1
 
                 else  -- "Reject"
-                    Stage.set("complete")
                     return {
                         promoted = false,
                         improvement = improvement,
@@ -3025,7 +2930,6 @@ Procedure {
             end
         end
 
-        Stage.set("complete")
         return {promoted = false, rejection_reason = "max_attempts_exhausted"}
     end
 }
@@ -3228,7 +3132,7 @@ Tactus includes first-class support for behavior-driven testing using Gherkin sy
 Write Gherkin specifications directly in procedure files:
 
 ```lua
-Specifications([[
+Specification([[
 Feature: Research Task Completion
   As a user
   I want the agent to research topics effectively
@@ -3240,11 +3144,6 @@ Feature: Research Task Completion
     Then the search tool should be called at least once
     And the done tool should be called exactly once
     And the procedure should complete successfully
-
-  Scenario: Agent progresses through stages correctly
-    Given the procedure has started
-    When the procedure runs
-    Then the stage should transition from researching to complete
     And the total iterations should be less than 20
 ]])
 ```
@@ -3258,16 +3157,12 @@ The framework provides comprehensive built-in steps for Tactus primitives:
 - `the {tool} tool should be called at least {n} times`
 - `the {tool} tool should be called with {param}={value}`
 
-**Stage steps:**
-- `the procedure has started`
-- `the stage should be {stage}`
-- `the stage should transition from {stage1} to {stage2}`
-
 **State steps:**
 - `the state {key} should be {value}`
 - `the state {key} should exist`
 
 **Completion steps:**
+- `the procedure has started`
 - `the procedure should complete successfully`
 - `the stop reason should contain {text}`