Experimenting/handlers

Cargo.toml

@@ -1,10 +1,21 @@
 [workspace]
 members = [
     "crates/theater",
-    "crates/theater-cli", 
+    "crates/theater-cli",
     "crates/theater-server",
     "crates/theater-server-cli",
-    "crates/theater-client"
+    "crates/theater-client",
+    "crates/theater-handler-environment",
+    "crates/theater-handler-filesystem",
+    "crates/theater-handler-http-client",
+    "crates/theater-handler-http-framework",
+    "crates/theater-handler-message-server",
+    "crates/theater-handler-process",
+    "crates/theater-handler-random",
+    "crates/theater-handler-runtime",
+    "crates/theater-handler-store",
+    "crates/theater-handler-supervisor",
+    "crates/theater-handler-timing", "crates/simple-theater",
 ]
 resolver = "2"
 

HANDLER_MIGRATION.md

@@ -0,0 +1,121 @@
+# Handler Migration Summary: Random Handler
+
+## What We Did
+
+Successfully migrated the `random` handler from the Theater core runtime into a standalone `theater-handler-random` crate.
+
+## Key Changes
+
+### 1. Created New Crate Structure
+- `/crates/theater-handler-random/`
+  - `Cargo.toml` - Dependencies and metadata
+  - `src/lib.rs` - Handler implementation
+  - `README.md` - Documentation
+
+### 2. Trait Simplification
+**Before:**
+```rust
+fn setup_host_functions(
+    &mut self,
+    actor_component: &mut ActorComponent,
+) -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>;
+```
+
+**After:**
+```rust
+fn setup_host_functions(
+    &mut self,
+    actor_component: &mut ActorComponent,
+) -> Result<()>;
+```
+
+**Why:** None of the handlers actually used `.await` in their setup functions. Making them synchronous:
+- Eliminated complex lifetime issues
+- Made the code more honest about what it does
+- Simplified implementation for all future handlers
+
+### 3. Handler Implementation
+- Renamed `RandomHost` → `RandomHandler`
+- Implemented the `Handler` trait with synchronous `setup_host_functions` and `add_export_functions`
+- Kept the async closures for actual random operations (those ARE async)
+- Maintained all existing functionality and chain event logging
+
+### 4. Dependencies
+The handler crate depends on:
+- Core theater crate (for trait definitions and types)
+- Wasmtime (for WASM integration)
+- Random generation (`rand`, `rand_chacha`)
+- Standard async/logging tools
+
+## Migration Pattern for Other Handlers
+
+Based on this migration, here's the pattern for migrating other handlers:
+
+1. **Create the crate** with proper Cargo.toml
+2. **Copy the host implementation** from `/crates/theater/src/host/`
+3. **Rename** `XxxHost` → `XxxHandler`
+4. **Implement the `Handler` trait:**
+   - `create_instance()` - Clone yourself
+   - `start()` - Async startup (keep as-is)
+   - `setup_host_functions()` - Now synchronous!
+   - `add_export_functions()` - Now synchronous!
+   - `name()`, `imports()`, `exports()` - Metadata
+5. **Update imports** to use `theater::` prefix
+6. **Test** and document
+
+## Benefits
+
+✅ **Cleaner architecture** - Handlers are independent modules
+✅ **Easier to maintain** - Each handler can evolve separately
+✅ **Better testing** - Test handlers in isolation
+✅ **Simpler lifetimes** - Synchronous trait methods avoid lifetime complexity
+✅ **Third-party handlers** - Clear pattern for custom handlers
+
+## Next Steps
+
+Recommended order for migrating remaining handlers:
+1. ✅ `random` - DONE!
+2. ✅ `environment` - DONE!
+3. `timing` - Also straightforward
+4. `http-client` - Moderate complexity
+5. `filesystem` - Larger but well-isolated
+6. `process`, `supervisor`, `store` - More complex, do last
+7. `message-server`, `http-framework` - Most complex
+
+## Testing
+
+The migrated handlers:
+- ✅ Compile without errors
+- ✅ All unit tests pass
+- ✅ Maintain backward compatibility
+- ✅ Integrate with Theater runtime via `Handler` trait
+
+## Completed Migrations
+
+### 1. Random Handler
+- **Crate**: `theater-handler-random`
+- **Status**: ✅ Complete
+- **Notes**: First migration, served as the documented example
+
+### 2. Timing Handler  
+- **Crate**: `theater-handler-timing`
+- **Status**: ✅ Complete
+- **Notes**: Completed prior to environment handler
+
+### 3. Environment Handler
+- **Crate**: `theater-handler-environment`
+- **Status**: ✅ Complete (2025-11-30)
+- **Notes**: 
+  - Fixed wasmtime version (26.0 → 31.0)
+  - Corrected closure signatures for func_wrap
+  - Updated all config fields in tests and docs
+  - All tests passing
+
+### 4. HTTP Client Handler
+- **Crate**: `theater-handler-http-client`
+- **Status**: ✅ Complete (2025-11-30)
+- **Notes**:
+  - Migrated component types (HttpRequest, HttpResponse)
+  - Preserved async operations with func_wrap_async
+  - Permission checking maintained
+  - All tests passing (3 unit + 1 doc)

README.md

@@ -1,81 +1,11 @@
 # Theater
 
-A WebAssembly actor system designed for secure, transparent, and reliable AI agent infrastructure.
+A WebAssembly actor runtime for reproducible, isolated, and observable programs.
 
-> [!NOTE]
-> This documentation is incomplete, please reach out to me at colinrozzi@gmail.com. I very much appreciate your interest and would love to hear from you! This project is in early development, breaking changes are expected, security is not guarenteed
+Every run in Theater produces a chain, created by hashing all of the information that crosses the wasm sandbox. Right now, this chain is mostly used for debugging, but there are many exciting 
 
-## The Challenge
+An actor's chain can be used for many things. First and currently most important, debugging. When an actor fails, you have a complete and reproducible record of everything that led up to that failure. Here is a sample run:
 
-AI agents present incredible opportunities for automation and intelligence, but they also introduce significant challenges. As autonomous AI agents become more capable and ubiquitous, we need infrastructure that can:
-
-1. **Contain and secure** agents with precise permission boundaries
-2. **Trace and verify** all agent actions for auditability and debugging
-3. **Manage failures** gracefully in complex agent systems
-4. **Orchestrate cooperation** between specialized agents with different capabilities
-
-## The Theater Approach
-
-Theater provides infrastructure specifically designed for AI agent systems. It moves trust from the individual agents to the system itself, providing guarantees at the infrastructure level:
-
-1. **WebAssembly Components** provide sandboxing and deterministic execution, ensuring agents can only access explicitly granted capabilities
-2. **Actor Model with Supervision** implements an Erlang-style supervision hierarchy for fault-tolerance and structured agent cooperation
-3. **Event Chain** captures every agent action in a verifiable record, enabling complete traceability and deterministic replay
-
-### Read more
-
-- **[Guide](https://colinrozzi.github.io/theater/guide)** - A comprehensive guide to Theater
-- **[Reference](https://colinrozzi.github.io/theater/api/theater)** - Full rustdoc documentation
-
-### To get started:
-1. Download [theater-server-cli](crates/theater-server-cli) 
-   ```bash
-   cargo install theater-server-cli
-   ```
-2. Download [theater-cli](crates/theater-cli) 
-   ```bash
-   cargo install theater-cli
-   ```
-3. Start the Theater server and leave it running in the background
-   ```bash
-   theater-server --log-stdout
-   ```
-4. Start an actor in a new terminal (this requires an actor, I will update this shortly with a link to a sample actor)
-   ```bash
-   theater start manifest.toml
-   ```
-5. Look at the running actors
-   ```bash
-   theater list
-   ```
-6. Look at an actor's event chain
-   ```bash
-   theater events <actor-id>
-   ```
-7. Stop an actor
-   ```bash
-   theater stop <actor-id>
-   ```
-
-
-### Manual Setup
-
-Most people will have these things, move on to cloning and download the dependencies as you need, but just for clarity you will need:
-
-1. Rust 1.81.0 or newer
-2. LLVM and Clang for building wasmtime
-3. CMake
-4. OpenSSL and pkg-config
-
-Then:
-
-1. Clone the repository:
-```bash
-git clone https://github.com/colinrozzi/theater.git
-cd theater
 ```
 
-2. Build the project:
-```bash
-cargo build
 ```