theater 0.3.8

A WebAssembly actor system for AI agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

package theater:simple;

// # Actor Interface
//
// Defines the core interface that all Theater actors must implement. This is the
// fundamental contract between the Theater runtime and WebAssembly actor components.
//
// ## Purpose
//
// The actor interface establishes the minimal required functionality for a component
// to be recognized and managed as a Theater actor. By implementing this interface,
// a WebAssembly component can be:
//
// - Loaded by the Theater runtime
// - Initialized with state and parameters
// - Managed within the supervision hierarchy
// - Integrated with the event chain system
//
// This interface is deliberately minimal to make it as easy as possible to create
// compatible actors, while still providing the core functionality needed for the
// Theater system to manage them.
//
// ## Example
//
// Here's how a typical actor would implement this interface in Rust:
//
// ```rust
// use ntwk::theater::actor::Guest;
// use ntwk::theater::types::State;
//
// struct MyActor;
//
// impl Guest for MyActor {
//     fn init(state: State) -> Result<(State,), String> {
//         // Create initial state if none exists
//         let new_state = match state {
//             Some(existing) => {
//                 // Use existing state
//                 existing
//             }
//             None => {
//                 // Create new initial state
//                 let initial_data = MyActorState {
//                     counter: 0,
//                     last_updated: chrono::Utc::now(),
//                 };
//                 serde_json::to_vec(&initial_data).map_err(|e| e.to_string())?
//             }
//         };
//
//         // Return the new state
//         Ok((new_state,))
//     }
// }
// ```
//
// ## Security
//
// This interface is the primary entry point for actor execution. The Theater runtime
// ensures that actors can only access resources they have been explicitly granted
// through handler configurations.
//
// ## Implementation Notes
//
// - The state parameter is passed as a blob of bytes, typically serialized/deserialized
//   using formats like JSON, MessagePack, or bincode.
// - Actors are responsible for managing their own state format and serialization.
// - The parameters tuple allows for flexible initialization with a variety of data types.
// - Returning an error string from the init function will cause the actor to fail to start.

interface actor {
    // # Initialize the actor
    //
    // Called when the actor is first started or restarted. This function is responsible
    // for setting up the actor's initial state.
    //
    // ## Parameters
    //
    // * `state` - Current state of the actor, or None if first initialization
    //
    // ## Returns
    //
    // * `Ok((state,))` - The updated state to store
    // * `Err(string)` - An error message if initialization fails
    //
    // ## Implementation Notes
    //
    // - If state is None, the actor should create a new initial state
    // - If state contains data, the actor should validate and use that state
    // - Any error returned will cause the actor to fail to start
    //
    // ## Note on Actor Identity
    //
    // The runtime's internal actor ID (TheaterId) is NOT passed to init. This is
    // intentional - the runtime ID is for internal bookkeeping only. If an actor
    // needs a stable identity (e.g., for messaging), it should use a separate
    // address concept configured through the manifest or obtained via host functions.
    init: func(state: option<list<u8>>) -> result<tuple<option<list<u8>>>, string>;
}