60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / MYSIS_ACCOUNT_MANAGEMENT.md
6.2 KB
1# Mysis Account Management 2 3**Version:** 3.0 4**Date:** 2026-02-09 5**Status:** Truth Document 6 7--- 8 9## Problem Statement 10 11Myses need game accounts to play SpaceMolt. Each mysis gets one account permanently assigned to eliminate timing races and enable reliable re-login. We need this account management to avoid polluting the server with more test accounts. 12 13**Constraint:** No changes to gameplay whatsoever. Myses must be able to call any game API freely. 14 15--- 16 17## Truth Table 18 19| Mysis Action | Mysis State | Pool State | System Behavior | Mysis Sees | 20|--------------|-------------|------------|-----------------|------------| 21| Calls `register(username, empire)` | No assigned account | Pool has available accounts | Proxy assigns pool account permanently, mimics MCP response with pool account details | `{result: {password, player_id}, session: {id, player_id, ...}}` (thinks it registered) | 22| Calls `register(username, empire)` | No assigned account | Pool is empty | Proxy passes to game server, captures response, stores new account, assigns permanently | `{result: {password, player_id}, session: {...}}` (actually registered) | 23| Calls `register(username, empire)` | Has assigned account | Any | Proxy returns error pointing to `login()` with assigned credentials | Error response | 24| Calls `login(username, password)` | Has assigned account | Any | Proxy substitutes assigned account credentials, passes to game server | `{result: {player, ship, system, poi, ...}, session: {...}}` (logged into assigned account) | 25| Calls `logout()` | Any | Any | Proxy passes to game server (account remains assigned) | Success | 26| Lists tools | Any | Any | N/A - `zoea_claim_account` removed entirely | Only game tools visible | 27 28--- 29 30## Behavior Rules 31 321. **Permanent assignment:** Once a mysis gets an account (via register), that account is permanently bound to `mysis_id` (stored in `assigned_to` field) 332. **First register - pool has accounts:** Proxy assigns pool account permanently, mimics game server `registered` response with pool account's password and player_id (never forwards to game server) 343. **First register - pool empty:** Proxy forwards register request to game server, captures response (password and player_id), stores new account in pool, assigns permanently to mysis 354. **Subsequent register:** When mysis with assigned account calls `register()`, proxy returns error: "Already have account. Use login(username, password)." 365. **Login substitution:** All `login()` calls from mysis with assigned account are silently substituted with assigned account credentials before passing to game server 376. **Account persistence:** Logout does NOT release account assignment - mysis keeps same account forever 387. **Account release:** Accounts return to pool ONLY when mysis is deleted/destroyed (assigned_to cleared) 398. **Internal claiming:** Account assignment is handled internally by proxy - no `zoea_claim_account` tool exists 40 41--- 42 43## State Transitions 44 45``` 46FIRST REGISTER - POOL HAS ACCOUNTS: 47Mysis: register(username, empire) → Proxy: assign_account(pool) → Proxy: mimic_MCP_response({result: {password, player_id}, session: {...}}) → Mysis: REGISTERED 48(Proxy never forwards to game server; mimics full MCP response structure with pool account credentials; account permanently bound to mysis_id) 49 50FIRST REGISTER - POOL EMPTY: 51Mysis: register(username, empire) → Game/MCP: {result: {password, player_id}, session: {...}} → Proxy: capture_response + store_account + assign_to_mysis → Mysis: REGISTERED 52(Request forwarded to game server; new account created; response captured; account stored in pool and permanently bound to mysis_id) 53 54SUBSEQUENT REGISTER: 55Mysis: register() → Proxy: error_response → Mysis: ERROR 56(Proxy returns MCP error: "Already have account. Use login(username, password).") 57 58LOGIN WITH ASSIGNED ACCOUNT: 59Mysis: login(any_user, any_pass) → Proxy: substitute(assigned_credentials) → Game/MCP: {result: {player, ship, system, poi, ...}, session: {...}} → Mysis: LOGGED_IN 60(Always logs into assigned account regardless of provided credentials; full game state returned) 61 62LOGOUT: 63Mysis: logout() → Game/MCP: success → Mysis: LOGGED_OUT 64(Account remains assigned to mysis_id for future login) 65 66MYSIS DELETION: 67Commander: delete_mysis() → Store: clear assigned_to → Pool gains available account 68``` 69 70--- 71 72## Verification 73 74| Scenario | Expected Outcome | 75|----------|------------------| 76| Pool has 3 accounts, new mysis calls register | Proxy mimics full MCP response with pool account's password/player_id/session (no game server call), account permanently assigned to mysis_id, pool has 2 available accounts | 77| Pool empty, new mysis calls register | Request forwarded to game server, MCP response captured (password/player_id/session), new account stored in pool and permanently assigned to mysis_id | 78| Mysis with assigned account calls register again | Mysis receives MCP error: "Already have account. Use login(username, password)." | 79| Mysis with assigned account calls login(wrong_user, wrong_pass) | Proxy substitutes assigned credentials, mysis gets full MCP response with `{result: {player, ship, system, poi, ...}, session: {...}}` for assigned account | 80| Mysis with assigned account calls logout | Mysis logged out, account remains assigned to mysis_id (can login again later) | 81| Mysis is deleted | Account's assigned_to cleared, account returns to available pool | 82| `make db-reset-accounts` run | All mysis assignments cleared (assigned_to = NULL), accounts return to pool, account details preserved | 83| Mysis lists tools | Only game tools visible (no `zoea_claim_account` - tool removed) | 84 85--- 86 87## Implementation Files 88 89- `internal/mcp/proxy.go` - Register interception, permanent assignment, login credential substitution, tool filtering 90- `internal/constants/constants.go` - System prompt (no auth instructions) 91- `internal/store/accounts.go` - Account pool management with `assigned_to` field 92- `Makefile` - `db-reset-accounts` target must clear `assigned_to` while preserving account details 93 94--- 95 96## Out of Scope 97 98- Review of other `zoea_*` tools (note: `zoea_claim_account` was removed entirely) 99- Account sharing between myses (one account = one mysis permanently) 100- Manual account reassignment (only via mysis deletion)