tactus 0.33.0__tar.gz → 0.34.0__tar.gz

{tactus-0.33.0 → tactus-0.34.0}/.github/workflows/release.yml

@@ -45,6 +45,9 @@ jobs:
       - name: Run behave BDD tests
         run: behave
 
+      - name: Run stdlib BDD tests
+        run: tactus stdlib test
+
   release:
     name: Semantic Release
     runs-on: ubuntu-latest

{tactus-0.33.0 → tactus-0.34.0}/AGENTS.md

@@ -2,6 +2,33 @@
 
 This document provides guidelines for AI coding agents working on the Tactus project.
 
+## Brand Theme & Visual Design Policies
+
+*   **Flat Design Only**:
+    *   No gradients.
+    *   No drop-shadows (unless totally flat/hard).
+    *   No borders/outlines on containers or regions.
+*   **Contrast & Separation**:
+    *   Avoid thin lines (hrules, borders) for separating regions.
+    *   Use **varying background colors** on flat rectangles with rounded corners to indicate regions and groupings.
+    *   Use contrast carefully; avoid high contrast.
+        *   Background black should not be fully black (e.g., use dark gray).
+        *   Foreground white should not be fully white.
+        *   Use a limited set of official colors: "not-black", "not-white", and 2-3 "muted" colors.
+*   **Color System**:
+    *   Themes use **Radix Colors** (Cool, Neutral, Warm).
+    *   Support both Light and Dark modes.
+*   **Typography & Layout**:
+    *   Refined elegance, modern Bauhaus-inspired, Apple's modern minimalist Art Deco.
+*   **Animations**:
+    *   Subtle animation effects are encouraged.
+    *   **NO CSS animations** (like Framer Motion) for components that feature in Babulus videos.
+    *   Use **frame-parameterized animations**: Animations must be driven by a `frame` parameter so they can be rendered deterministically in videos.
+*   **Development Workflow**:
+    *   Refer to **Shadcn UI** for default UX design patterns.
+    *   Provide examples of basic visual elements in **Storybook stories**.
+    *   Do research into best practices for specific tasks.
+
 ## Pre-Commit Checklist
 
 **CRITICAL**: Before committing any changes, you MUST:
@@ -47,6 +74,13 @@ Do not skip this step or commit before getting approval and running these checks
 - **Multiple models**: Different agents can use different models (e.g., GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet)
 - **Model parameters**: Supports model-specific parameters like `temperature`, `max_tokens`, `openai_reasoning_effort`
 
+**Provider-Specific Dependencies**:
+- **DO NOT add provider-specific SDK dependencies** (e.g., `openai`, `anthropic`, etc.) unless there is a SPECIFIC reason
+- Tactus uses **LiteLLM (via DSPy)** for ALL LLM calls, which provides unified multi-provider support
+- LiteLLM handles all provider-specific API calls internally
+- Adding provider SDKs creates maintenance burden and can lead to bugs where code bypasses the LiteLLM layer
+- Exception: `boto3` is needed for Bedrock support, but all actual LLM calls still go through LiteLLM
+
 Example:
 ```lua
 -- Tool definition
@@ -213,8 +247,34 @@ Only rebuild when:
 
 **Never rebuild for regular code changes** - that's what dev mode prevents.
 
+### CRITICAL: Auto-Rebuild on Code Changes
+
+**IMPORTANT**: The sandbox automatically rebuilds when it detects changes to core Tactus files. The hash includes:
+- `tactus/dspy/` - DSPy integration
+- `tactus/adapters/` - Adapters
+- `tactus/broker/` - Broker client (used by sandbox for API calls)
+- `tactus/core/` - Core runtime
+- `tactus/primitives/` - Primitives
+- `tactus/sandbox/` - Sandbox infrastructure
+- `tactus/stdlib/` - Standard library
+- `tactus/docker/` - Docker configuration
+- `pyproject.toml` - Dependencies
+
+**Common Pitfall**: When you make changes to these files (especially `tactus/broker/client.py`), the sandbox image is automatically rebuilt on the next `tactus run` command. However, AI agents often forget this and run tests with outdated containers, leading to confusing errors like:
+- `TypeError: BrokerClient.llm_chat() got an unexpected keyword argument 'tools'`
+- New parameters not being recognized
+- Changes seemingly not taking effect
+
+**Solution**: After making changes to any of the above paths, the next `tactus run` will automatically rebuild the sandbox image with your new code. Just wait for the rebuild to complete before declaring victory. Look for log lines indicating the build is happening.
+
 See [docs/development-mode.md](docs/development-mode.md) for complete details.
 
+### Docker Sandbox Defaults (CLI)
+
+- The CLI requires Docker sandboxing by default. If Docker is unavailable, `tactus run` should error rather than silently running without isolation.
+- Easy opt-out is explicit: `--no-sandbox` or `sandbox.enabled: false`.
+- For PyPI installs without a local source tree, the sandbox image builds by installing the matching Tactus version from PyPI inside the container.
+
 ## Tactus IDE Development
 
 When working on the Tactus IDE:
@@ -293,6 +353,9 @@ The IDE is designed to run as a desktop application:
 When working on the Tactus IDE frontend:
 
 - **UI Framework**: Use [Shadcn UI](https://ui.shadcn.com/) components for all UI elements
+- **AI Components**: Use [AI SDK Elements](https://ai-sdk.dev/elements) components by default for AI-related UI patterns
+  - Confirmation dialogs: Use the [Confirmation component](https://ai-sdk.dev/elements/components/confirmation) pattern
+  - Follow AI SDK Elements patterns for conversational interfaces, prompts, and responses
 - **Icons**: Always use [Lucide React](https://lucide.dev/) icons - **NEVER use emojis**
 - **Styling**: Use Tailwind CSS with the existing design system
 - **Theme**: Support both light and dark modes (colors are defined in CSS variables)

{tactus-0.33.0 → tactus-0.34.0}/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 <!-- version list -->
 
+## v0.34.0 (2026-01-25)
+
+### Bug Fixes
+
+- Address ruff warnings
+  ([`8523ff0`](https://github.com/AnthusAI/Tactus/commit/8523ff0fb54a3cc961869cb243c27efca84fcd9b))
+
+- Clarify sandbox defaults and CLI failures
+  ([`1bdc1d9`](https://github.com/AnthusAI/Tactus/commit/1bdc1d9a5d9552a1972845646248746f2dfa35e6))
+
+- Enable agent tool calling with DSPy native function calling
+  ([`a76ea99`](https://github.com/AnthusAI/Tactus/commit/a76ea99d79732f6e39e242e733c3918cf7aca76c))
+
+- Enable mocks for custom steps
+  ([`b777f6b`](https://github.com/AnthusAI/Tactus/commit/b777f6b033f297ef6dc5ceae262a41b56d11b680))
+
+- Enable real-time streaming for IDE agent responses
+  ([`55266d7`](https://github.com/AnthusAI/Tactus/commit/55266d7b840bfa52121ec76a8353dd8d074f9760))
+
+- Enforce sandbox defaults and PyPI image build
+  ([`af17c15`](https://github.com/AnthusAI/Tactus/commit/af17c15d384cc475cb5128fcf0776eba522880ba))
+
+- Make Classify primitive deterministic in BDD
+  ([`0c58e55`](https://github.com/AnthusAI/Tactus/commit/0c58e554b46653abfa834d1a536ac964290428f4))
+
+- Mock LLM classify examples in BDD
+  ([`8277d3e`](https://github.com/AnthusAI/Tactus/commit/8277d3e99f8612bf3d65447ebe451f75337da715))
+
+- Pass mock manager into BDD runtime context
+  ([`76fd440`](https://github.com/AnthusAI/Tactus/commit/76fd4408e9afc58bf9c3116b25605f7ac0d30d89))
+
+- Register generate agent mocks
+  ([`6faf28c`](https://github.com/AnthusAI/Tactus/commit/6faf28c9f289eb45b633ae11d8a0e02311023c74))
+
+- Stabilize stdlib generate specs
+  ([`e6a00cb`](https://github.com/AnthusAI/Tactus/commit/e6a00cb494756ff5eeb07f3b55ec1a8e875a06ba))
+
+- Update dependencies and improve CI configuration
+  ([`a063fa5`](https://github.com/AnthusAI/Tactus/commit/a063fa59272e2192305c8a7806185f8fcb0bcafd))
+
+- Update MockHITLHandler to accept execution_context parameter
+  ([`14cd888`](https://github.com/AnthusAI/Tactus/commit/14cd888a4a6cdd05457158cb904a07cb14df4bb8))
+
+### Chores
+
+- Report stdlib scenario failures
+  ([`7aa5093`](https://github.com/AnthusAI/Tactus/commit/7aa5093a7e98c217e32c3483d39e7d44820c24da))
+
+### Code Style
+
+- Apply black 26.1.0 formatting
+  ([`d189f41`](https://github.com/AnthusAI/Tactus/commit/d189f4121ead45b4bb44599a9def9c40ef7c1983))
+
+### Documentation
+
+- Add brand theme and visual design policies
+  ([`ca2ea2d`](https://github.com/AnthusAI/Tactus/commit/ca2ea2d388179b5bea4d4a4650b896d20fa7f974))
+
+- Comprehensive checkpoint/resume testing summary
+  ([`54b9ec9`](https://github.com/AnthusAI/Tactus/commit/54b9ec998492ab31e6065a4ae3777b7d5f1ece59))
+
+- Document LLM checkpointing implementation
+  ([`3906604`](https://github.com/AnthusAI/Tactus/commit/3906604e7f887a4cfe2e4e6557162527b61382d0))
+
+- Mark Phase 2 complete, ready for Phase 3 IDE/SSE channel
+  ([`8db044e`](https://github.com/AnthusAI/Tactus/commit/8db044e111f1a5d348179c54fe3b24be515ea7d9))
+
+- Mark Test 3 (LLM Checkpoint/Resume) complete
+  ([`6eb0043`](https://github.com/AnthusAI/Tactus/commit/6eb00435039a2d37107579eb5ab4c3a07374a46c))
+
+- Update checkpoint testing status - Test 2 complete
+  ([`b5b4bd8`](https://github.com/AnthusAI/Tactus/commit/b5b4bd818aaeb84a766c58ce9b0403e70b2899b5))
+
+- Update status to Phase 4 testing, remove emojis
+  ([`1392959`](https://github.com/AnthusAI/Tactus/commit/139295971b2575f26e4ee41ac2e243f7d65a5c24))
+
+### Features
+
+- Add modal cancellation handling with reopen capability
+  ([`392660c`](https://github.com/AnthusAI/Tactus/commit/392660ca4a693975bbc463e38e3323ed9e53113a))
+
+- Complete IDE HITL integration with SSE channel
+  ([`5bf5e41`](https://github.com/AnthusAI/Tactus/commit/5bf5e4106a90b291cf6d331cd43e6f6c0fd1c9d8))
+
+- Complete Phase 2 runtime integration with rich metadata
+  ([`b265eb9`](https://github.com/AnthusAI/Tactus/commit/b265eb9b2bbb9f9e79b990b1c7664b6e0a547407))
+
+- Complete unified HITL component registry architecture
+  ([`4005ae7`](https://github.com/AnthusAI/Tactus/commit/4005ae7baa70c6bba18c9b14fc57dfc05f0d4f4a))
+
+- Enable real-time container HITL and event streaming
+  ([`a6e49ff`](https://github.com/AnthusAI/Tactus/commit/a6e49ff2bac5cae149bd4595c632e6b0b4863250))
+
+- Implement DSPy native tool calling with Pydantic AI toolsets
+  ([`f061f37`](https://github.com/AnthusAI/Tactus/commit/f061f374babbb15aaa2ba145ebffd536f2c02f55))
+
+- Implement inline rendering for batched HITL inputs with registry architecture
+  ([`9b520ba`](https://github.com/AnthusAI/Tactus/commit/9b520ba242afd15f26f452c0d41a59e864cb7bbe))
+
+- Implement LLM checkpointing for transparent durability
+  ([`15c0139`](https://github.com/AnthusAI/Tactus/commit/15c0139028f1c9da7eb7900450113ccf37871e93))
+
+- Transparent durability for HITL with checkpoint/resume
+  ([`46a3791`](https://github.com/AnthusAI/Tactus/commit/46a3791d6e8c130eb29e156ef029de2bb9ad3ced))
+
+- **stdlib**: Implement standard library with classify, extract, and generate modules
+  ([`a274a1e`](https://github.com/AnthusAI/Tactus/commit/a274a1e4407ff07eb51ca16f60403b1b4757b522))
+
+### Testing
+
+- Add LLM checkpoint/resume test procedure
+  ([`88e06e5`](https://github.com/AnthusAI/Tactus/commit/88e06e56f21cbefe8f03491a74f545514eb88796))
+
+- Add Test 4 and Test 5 procedures
+  ([`d181355`](https://github.com/AnthusAI/Tactus/commit/d181355b9e4233fb54e9894b3f109f8dcfdefb6b))
+
+- Add Tests 6-8 procedures and manual testing guide
+  ([`9c27030`](https://github.com/AnthusAI/Tactus/commit/9c270305fc73036e4bb180ddccaf5f6f8291da7a))
+
+
 ## v0.33.0 (2026-01-18)
 
 ### Documentation

tactus-0.34.0/CHANGES_SUMMARY.md

@@ -0,0 +1,176 @@
+# Summary of Changes: Plain Function main() Support
+
+## Overview
+
+Fixed HITL examples that use plain Lua `function main()` syntax instead of the DSL `Procedure { ... }` syntax. These examples were previously non-functional because the runtime didn't recognize or execute plain function definitions.
+
+## Files Modified
+
+### 1. [tactus/core/runtime.py](tactus/core/runtime.py)
+
+#### Change A: Skip script mode transformation for named functions (Lines 2451-2454)
+```python
+# If there are named function definitions (function name()), don't transform.
+# These are procedure definitions that will be explicitly called.
+if re.search(r"(?m)^\s*(?:local\s+)?function\s+[A-Za-z_][A-Za-z0-9_]*\s*\(", source):
+    return source
+```
+
+**Why:** The script mode transformation was incorrectly wrapping files containing `function main()` definitions, causing the function to be defined inside a wrapper but never called.
+
+#### Change B: Auto-register plain main() functions (Lines 2754-2781)
+```python
+# Auto-register plain function main() if it exists
+#
+# Some .tac files use plain Lua syntax: `function main() ... end`
+# instead of the Procedure DSL syntax: `Procedure { function(input) ... end }`
+#
+# For these files, we need to explicitly check lua.globals() after execution
+# and register any function named "main" as the main procedure.
+#
+# This allows both syntax styles to work:
+# 1. DSL style (self-registering): Procedure { function(input) ... end }
+# 2. Plain Lua style (auto-registered): function main() ... end
+#
+# The script mode transformation (in _maybe_transform_script_mode_source)
+# is designed to skip files with named function definitions to avoid wrapping
+# them incorrectly.
+lua_globals = sandbox.lua.globals()
+if "main" in lua_globals:
+    main_func = lua_globals["main"]
+    # Check if it's a function and not already registered
+    if callable(main_func) and "main" not in builder.registry.named_procedures:
+        logger.info("[AUTO_REGISTER] Found plain function main(), auto-registering as main procedure")
+        builder.register_named_procedure(
+            name="main",
+            lua_function=main_func,
+            input_schema={},
+            output_schema={},
+            state_schema={},
+        )
+```
+
+**Why:** After executing the Lua file, we need to check if a `main` function was defined in the global scope and explicitly register it as a named procedure so `_execute_workflow()` can find and execute it.
+
+#### Change C: Removed debug print statements (Lines 2334-2338, 2344, 2354, 2358, 2373, 2376)
+Removed temporary debug prints added during investigation:
+- `print(f"[DEBUG] self.registry = ...")`
+- `print(f"[DEBUG] Registry exists, named_procedures = ...")`
+- `print("[DEBUG] Found 'main' in named_procedures")`
+- `print(f"[DEBUG] main_proc = ...")`
+- `print("[DEBUG] Creating ProcedureCallable...")`
+- `print(f"[DEBUG] Created main_callable: ...")`
+- `print(f"[DEBUG] input_params = ...")`
+- `print("[DEBUG] About to call main_callable()...")`
+- `print(f"[DEBUG] main_callable() returned: ...")`
+
+### 2. [tactus/core/execution_context.py](tactus/core/execution_context.py)
+
+#### Change: Removed debug print statements (Lines 302, 306)
+```python
+# Removed:
+# print(f"[DEBUG] wait_for_human: hitl={self.hitl}, type={type(self.hitl)}")
+# print(f"[DEBUG] No HITL handler - returning default: {default_value}")
+```
+
+### 3. [tactus/primitives/procedure_callable.py](tactus/primitives/procedure_callable.py)
+
+#### Change A: Removed debug print statements (Lines 95, 129-138, 149, 153)
+```python
+# Removed:
+# print(f"[DEBUG PROC] Inside execute_procedure() for {self.name}")
+# print(f"[DEBUG PROC] About to call procedure_function")
+# print(f"[DEBUG PROC] self.procedure_function = {self.procedure_function}")
+# print(f"[DEBUG PROC] type = {type(self.procedure_function)}")
+# print(f"[DEBUG PROC] Trying to call with NO parameters...")
+# print(f"[DEBUG PROC] NO-PARAM call returned: {result}")
+# print(f"[DEBUG PROC] ERROR calling procedure_function: {e}")
+# print(f"[DEBUG PROC] Converted to dict: {result}")
+# print(f"[DEBUG PROC] Validation passed, returning: {result}")
+```
+
+#### Change B: Fixed function call to pass lua_params (Line 128)
+```python
+# Before (incorrect):
+result = self.procedure_function()
+
+# After (correct):
+result = self.procedure_function(lua_params)
+```
+
+**Why:** The Lua function `main(input)` expects a parameter. Even if the function doesn't use the input, we should still pass an empty table to match the expected signature.
+
+## Documentation Files Created
+
+1. **HITL_FIX_SUMMARY.md** - Comprehensive explanation of the problem, root cause, solution, and impact
+2. **EXECUTION_TRACE.md** - Step-by-step trace of execution flow showing how the fix works
+3. **CHANGES_SUMMARY.md** - This file, documenting all code changes
+
+## Test Files Created
+
+1. **test_full_flow.py** - Verifies Lupa can find and call plain function definitions
+2. **test_transform_full.py** - Verifies script mode transformation is skipped for named functions
+3. **test_auto_register.py** - Documents the auto-registration logic flow
+
+## Impact
+
+### ✅ What Now Works
+
+- `examples/90-hitl-simple.tac` - Full HITL demo with approve/input/review
+- `examples/90-super-simple.tac` - Minimal test case
+- `examples/90-test-params.tac` - Parameter passing test
+- Any .tac file using `function main()` syntax
+
+### ✅ Backward Compatibility
+
+- No breaking changes
+- Existing DSL-style procedures continue to work unchanged
+- This is purely a bug fix for previously non-working code
+
+### ✅ Both Syntax Styles Supported
+
+**DSL Style (unchanged):**
+```lua
+Procedure {
+    output = { result = field.string{required = true} },
+    function(input)
+        local approved = Human.approve({message = "Continue?"})
+        return {result = "done"}
+    end
+}
+```
+
+**Plain Lua Style (now fixed):**
+```lua
+function main(input)
+    local approved = Human.approve({message = "Continue?"})
+    return {result = "done"}
+end
+```
+
+## Expected Behavior
+
+Running `tactus examples/90-hitl-simple.tac` should now:
+
+1. ✅ Execute top-level prints
+2. ✅ Auto-register `function main()`
+3. ✅ Execute `main()` function body
+4. ✅ Show HITL prompts for `Human.approve()`, `Human.input()`, `Human.review()`
+5. ✅ Wait for user input at CLI
+6. ✅ Resume execution after user responds
+7. ✅ Complete workflow successfully with result
+
+## Testing Instructions
+
+```bash
+# With Python 3.11+ environment
+tactus examples/90-hitl-simple.tac
+
+# Or run individual test scripts
+python3 test_full_flow.py        # Tests Lupa function execution
+python3 test_transform_full.py   # Tests transformation logic
+```
+
+## Next Steps
+
+The fix is complete and ready for testing with Python 3.11+. All debug code has been removed, and the implementation is clean and well-documented.

tactus-0.34.0/CHECKPOINT_RESUME_PLAN.md

@@ -0,0 +1,255 @@
+# Checkpoint and Resume Implementation Plan
+
+## Problem Statement
+
+Currently, when a procedure hits `Human.approve()` or other HITL calls:
+1. ✅ It raises `ProcedureWaitingForHuman`
+2. ✅ The pending request is stored in storage backend
+3. ❌ **ON RESUME: The runtime doesn't check for existing responses**
+4. ❌ **The procedure reruns from scratch, not from checkpoint**
+
+**Required behavior:**
+- Kill a procedure waiting for human input (Ctrl+C)
+- Restart the procedure
+- It should resume from the exact checkpoint where it was waiting
+- LLM calls should return the same cached results
+- Human responses should be retrieved from storage if available
+
+## Current State
+
+### What Works ✅
+- `ControlLoopHandler._store_pending()` - Stores pending HITL request
+- `ControlLoopHandler.check_pending_response()` - Can retrieve stored responses
+- `ProcedureWaitingForHuman` exception raised and caught
+- Storage backend supports `get_state()` and `set_state()`
+
+### What's Missing ❌
+
+1. **Resume Flow Not Implemented**
+   - Runtime doesn't check `check_pending_response()` on restart
+   - No logic to skip to the checkpoint position
+   - No integration with execution log checkpoints
+
+2. **LLM Completion Caching**
+   - No caching of LLM responses for deterministic replay
+   - Need to store completions in execution log
+   - Need to replay from cache on resume
+
+3. **Checkpoint Position Tracking**
+   - Need to know which checkpoint we're resuming from
+   - Need to skip already-executed steps
+   - Need to restore Lua execution state
+
+## Implementation Steps
+
+### Phase 1: Basic Resume Flow
+
+**Goal:** Kill and restart a procedure waiting for HITL, have it check storage for response and continue.
+
+**Files to Modify:**
+
+1. **`tactus/core/runtime.py`** - Add resume check at start of execution:
+```python
+async def execute(self, ...):
+    # ... existing setup ...
+
+    # Check for pending HITL responses BEFORE executing workflow
+    if self.control_handler and self.storage:
+        pending_responses = await self._check_pending_control_responses(procedure_id)
+        if pending_responses:
+            logger.info(f"Found {len(pending_responses)} pending control responses, resuming...")
+            # Store these for the control loop to return immediately
+            self._pending_responses = pending_responses
+
+    # ... continue with normal execution ...
+
+async def _check_pending_control_responses(self, procedure_id: str):
+    """Check storage for any pending control responses."""
+    state = self.storage.get_state(procedure_id) or {}
+    responses = {}
+    for key, value in state.items():
+        if key.startswith("control_pending:"):
+            if value.get("response"):
+                request_id = key.replace("control_pending:", "")
+                responses[request_id] = ControlResponse(**value["response"])
+    return responses
+```
+
+2. **`tactus/adapters/control_loop.py`** - Check for cached responses first:
+```python
+async def _request_interaction_async(self, request: ControlRequest) -> ControlResponse:
+    # Check if we already have a response from previous run
+    if self.storage:
+        cached_response = self.check_pending_response(
+            request.procedure_id,
+            request.request_id
+        )
+        if cached_response:
+            logger.info(f"Using cached response for {request.request_id}")
+            return cached_response
+
+    # ... existing fanout logic ...
+```
+
+3. **Store responses when received:**
+```python
+# In _request_interaction_async, after getting response:
+if response and self.storage:
+    self._store_response(request, response)
+```
+
+### Phase 2: LLM Completion Caching
+
+**Goal:** Cache LLM completions in execution log so reruns are deterministic.
+
+**Approach:**
+- Execution log already exists (ProcedureMetadata.execution_log)
+- Add LLM completions to checkpoints
+- On resume, replay cached completions
+
+**Files to Modify:**
+
+1. **`tactus/core/execution_context.py`** - Cache LLM completions:
+```python
+async def chat_completion(self, messages, ...):
+    # Check if we have a cached completion for this position
+    if self.storage and self.resume_mode:
+        cached = self._get_cached_completion(position=self.current_checkpoint)
+        if cached:
+            logger.info(f"Using cached LLM completion at checkpoint {self.current_checkpoint}")
+            return cached
+
+    # Call LLM
+    result = await self.client.create_completion(...)
+
+    # Store in execution log for future resume
+    if self.storage:
+        self._store_completion(position=self.current_checkpoint, result=result)
+
+    return result
+```
+
+### Phase 3: Checkpoint-Based Resume
+
+**Goal:** Skip already-executed steps, resume from exact checkpoint.
+
+**Approach:**
+- Track execution position in Lua state
+- On resume, fast-forward to the checkpoint position
+- This is more complex and may require Lua coroutine management
+
+## Test Plan
+
+### Test 1: Basic HITL Resume (No LLM)
+
+```lua
+-- test-resume-basic.tac
+function main()
+    print("Step 1: Before HITL")
+    local approved = Human.approve("Should we continue?")
+    print("Step 2: After HITL, approved=" .. tostring(approved))
+    return {approved = approved}
+end
+```
+
+**Test Steps:**
+1. Run: `tactus run test-resume-basic.tac`
+2. Wait for "Should we continue?" prompt
+3. Kill with Ctrl+C
+4. Respond via control CLI: `tactus control --respond y`
+5. Restart: `tactus run test-resume-basic.tac`
+6. **Expected:** Should NOT print "Step 1" again, should continue from HITL
+7. **Expected:** Should print "Step 2: After HITL, approved=true"
+
+### Test 2: LLM + HITL Resume
+
+```lua
+-- test-resume-llm.tac
+function main()
+    print("Step 1: Calling LLM")
+    local result = Agent.run({
+        prompt = "Generate a random joke",
+        model = "gpt-3.5-turbo"
+    })
+    print("Step 2: LLM returned: " .. result.output)
+
+    print("Step 3: Asking for approval")
+    local approved = Human.approve("Like this joke?")
+
+    print("Step 4: Done, approved=" .. tostring(approved))
+    return {joke = result.output, approved = approved}
+end
+```
+
+**Test Steps:**
+1. Run: `tactus run test-resume-llm.tac`
+2. Let LLM complete, note the joke
+3. Wait for approval prompt
+4. Kill with Ctrl+C
+5. Respond via control CLI: `tactus control --respond y`
+6. Restart: `tactus run test-resume-llm.tac`
+7. **Expected:** Should NOT call LLM again (cached completion)
+8. **Expected:** Should show SAME joke as first run
+9. **Expected:** Should skip to "Step 4: Done"
+
+### Test 3: Multiple HITL Points
+
+```lua
+-- test-resume-multi.tac
+function main()
+    print("Step 1")
+    local first = Human.approve("First question?")
+    print("Step 2, first=" .. tostring(first))
+
+    local second = Human.approve("Second question?")
+    print("Step 3, second=" .. tostring(second))
+
+    return {first = first, second = second}
+end
+```
+
+**Test Steps:**
+1. Run, respond to first question with 'y', kill at second question
+2. Respond to second via control CLI: `tactus control --respond n`
+3. Restart
+4. **Expected:** Should skip first question (already answered)
+5. **Expected:** Should use cached response for second question
+6. **Expected:** Should complete immediately
+
+## Success Criteria
+
+✅ **Phase 1 Complete When:**
+- Can kill at HITL prompt, respond via control CLI, restart, and continue
+- Procedure doesn't rerun from start
+- Stored response is used
+
+✅ **Phase 2 Complete When:**
+- LLM calls are cached in execution log
+- Reruns use cached completions (deterministic)
+- Can verify completion is identical across runs
+
+✅ **Phase 3 Complete When:**
+- Can handle multiple HITL points with partial progress
+- Execution jumps to correct checkpoint position
+- All prior state is properly restored
+
+## Timeline Priority
+
+**CRITICAL - Do This First:**
+- Phase 1: Basic resume flow (essential infrastructure)
+- Test 1: Verify basic HITL resume works
+
+**HIGH - Do Next:**
+- Phase 2: LLM caching (needed for determinism)
+- Test 2: Verify LLM + HITL resume
+
+**MEDIUM - Nice to Have:**
+- Phase 3: Multi-checkpoint resume
+- Test 3: Verify multiple HITL points
+
+## Notes
+
+- Storage backend already supports `get_state()` and `set_state()`
+- Execution log structure already exists in `ProcedureMetadata`
+- The hard part is integrating the resume check at the right point in the runtime
+- May need to add a "resume mode" flag to know we're resuming vs. fresh start