theater 0.3.12

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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

package theater:simple;

interface supervisor {
    use types.{chain-event};
    // # Spawn a new child actor
    //
    // Creates and starts a new actor from the specified manifest file.
    //
    // ## Parameters
    //
    // * `manifest` - Path or content of the manifest file describing the actor
    // * `init-bytes` - Optional initial state for the actor (serialized bytes)
    //
    // ## Returns
    //
    // * `Ok(string)` - ID of the newly created actor
    // * `Err(string)` - Error message if spawning fails
    spawn: func(manifest: string, init-bytes: option<list<u8>>) -> result<string, string>;

    // # Resume a previously stopped child actor
    //
    // Restarts a previously created actor using an existing manifest but with a potentially
    // new initial state.
    //
    // ## Parameters
    //
    // * `manifest` - Path or content of the manifest file describing the actor
    // * `init-state` - Optional new initial state for the actor (serialized bytes)
    //
    // ## Returns
    //
    // * `Ok(string)` - ID of the resumed actor
    // * `Err(string)` - Error message if resuming fails
    resume: func(manifest: string, init-state: option<list<u8>>) -> result<string, string>;
    
    // # List all child actors
    //
    // Retrieves a list of all children directly managed by this actor.
    //
    // ## Returns
    //
    // * `list<string>` - IDs of all child actors
    list-children: func() -> list<string>;
    
    // # Stop a specific child actor
    //
    // Gracefully stops a child actor identified by its ID.
    //
    // ## Parameters
    //
    // * `child-id` - ID of the child actor to stop
    //
    // ## Returns
    //
    // * `Ok(_)` - Child was successfully stopped
    // * `Err(string)` - Error message if stopping fails
    stop-child: func(child-id: string) -> result<_, string>;
    
    // # Restart a specific child actor
    //
    // Stops and then starts a child actor, maintaining its ID but resetting its state.
    //
    // ## Parameters
    //
    // * `child-id` - ID of the child actor to restart
    //
    // ## Returns
    //
    // * `Ok(_)` - Child was successfully restarted
    // * `Err(string)` - Error message if restarting fails
    restart-child: func(child-id: string) -> result<_, string>;
    
    // # Get the latest state of a child actor
    //
    // Retrieves the current serialized state of a specified child actor.
    //
    // ## Parameters
    //
    // * `child-id` - ID of the child actor
    //
    // ## Returns
    //
    // * `Ok(option<list<u8>>)` - Current state of the child (None if no state)
    // * `Err(string)` - Error message if retrieving state fails
    get-child-state: func(child-id: string) -> result<option<list<u8>>, string>;
    
    // # Get event history of a child actor
    //
    // Retrieves the chain of events that have occurred in a child actor,
    // providing visibility into its execution history.
    //
    // ## Parameters
    //
    // * `child-id` - ID of the child actor
    //
    // ## Returns
    //
    // * `Ok(list<chain-event>)` - List of events in the child's chain
    // * `Err(string)` - Error message if retrieving events fails
    get-child-events: func(child-id: string) -> result<list<chain-event>, string>;
}

interface supervisor-handlers {
    use types.{wit-actor-error};
    
    // # Handle a child actor error
    //
    // Processes an error from a child actor, allowing the parent to react or log the error.
    //
    // ## Parameters
    //
    // * `state` - Optional state of the parent actor (for context)
    // * `params` - Tuple containing the child ID and error data
    //
    // ## Returns
    //
    // * `Ok(tuple<option<list<u8>>, string>)` - Updated state and result message
    // * `Err(string)` - Error message if handling fails
    handle-child-error: func(state: option<list<u8>>, params: tuple<string, wit-actor-error>) -> result<tuple<option<list<u8>>>, string>;

    handle-child-exit: func(state: option<list<u8>>, params: tuple<string, option<list<u8>>>) -> result<tuple<option<list<u8>>>, string>;

    handle-child-external-stop: func(state: option<list<u8>>, params: tuple<string>) -> result<tuple<option<list<u8>>>, string>;
}