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.