xonecas.io
60255
Zn

Zoea-Nova / files

Zoea-Nova / documentation / architecture / MYSIS_STATE_MACHINE.md

2.7 KB
1# Mysis State Machine
2
3This document describes the valid Mysis lifecycle states and the transitions between them.
4
5## States
6
7- `idle`: Not running, but accepts messages. Messages are stored and processed when started. Set on creation and when a mysis fails 3 nudges; requires a commander message/broadcast or explicit start to resume processing.
8- `running`: Active and eligible for nudges; waiting between loop iterations. Accepts messages.
9- `stopped`: Explicitly stopped by user action. Rejects messages until relaunched.
10- `errored`: Provider or MCP failures after retries; recorded as `lastError`. Rejects messages until relaunched.
11
12## Activity (not a state)
13
14- `thinking` is represented by `ActivityStateLLMCall` (not a MysisState).
15- In-game activities (traveling, cooldown, etc.) are for context/TUI only and do not block nudges.
16
17## Diagram
18
19```mermaid
20stateDiagram-v2
21    [*] --> idle: create or load
22    idle --> running: start
23    running --> idle: 3 nudges failed
24    running --> stopped: stop
25    running --> errored: error
26    stopped --> running: relaunch
27    errored --> running: relaunch
28```
29
30## Transition Triggers
31
32### Create or Load
33
34- When a Mysis is created in the store, its state is `idle`.
35- When a Mysis is loaded at startup, the runtime instance starts in `idle` and must be explicitly started.
36
37### Start (Relaunch)
38
39- Triggered by `Commander.StartMysis` (TUI `r` key).
40- Transitions to `running` from `idle`, `stopped`, or `errored`.
41- If the store update fails during start, the Mysis remains unchanged and returns an error.
42
43### Stop
44
45- Triggered by `Commander.StopMysis` (TUI `s` key).
46- Valid only when currently `running`.
47- Transitions to `stopped` and releases the current account.
48
49### Error
50
51 - Triggered by `setErrorState` on execution failures (provider or MCP after retries).
52 - Transitions to `errored` and records `lastError`.
53
54### Idle (Nudge Breaker)
55
56- Triggered after 3 failed nudges with no progress.
57- Transitions to `idle` and signals that manual attention is needed.
58
59## Message Acceptance
60
61Messages can be sent to Myses in `idle` and `running` states:
62
63- **`idle`**: Accepts messages. Messages are stored and will be processed when the Mysis is started.
64- **`running`**: Accepts messages. Messages are processed immediately.
65- **`stopped`**: Rejects messages with error "mysis stopped - press 'r' to relaunch"
66- **`errored`**: Rejects messages with error "mysis errored - press 'r' to relaunch"
67
68User-initiated stop (`stopped` state) and error conditions (`errored` state) require explicit relaunch before messages can be sent.
69
70## Notes
71
72- State updates are persisted via `store.UpdateMysisState`.
73- Messages are accepted in `idle` and `running` states; rejected in `stopped` and `errored` states.