xonecas.io
60255
Zn

Zoea-Nova / commit abb915e

fix: respect rate limit retry headers

xonecas2026-02-09 abb915e06d870cb53a31df71e9804f7670a92099 parent f0416b6

3 files changed

GAME_STATE_CACHE_DESIGN.md+269−0
@@ -0,0 +1,269 @@
1+# Game State Cache Design
2+
3+## Problem
4+
5+Myses are stuck in a loop of re-requesting game state every turn:
6+
7+1. **Turn N:** Mysis calls `get_status`, `get_ship`, `get_map` → receives 190 KB of data
8+2. **Turn N+1:** Synthetic nudge starts new turn
9+ - Historical context contains old snapshots (compressed)
10+ - LLM doesn't trust "stale" data
11+ - Calls `get_status` again → another 190 KB
12+3. **Repeat forever:** Massive payloads every turn, hits 10-iteration limit
13+
14+**Root cause:** LLMs can't tell if snapshot data is from 1 turn ago or 10 turns ago. They re-request to be safe.
15+
16+## Solution: Incremental Game State Cache
17+
18+Build and maintain game state incrementally as the mysis plays. Show state with recency metadata so LLM knows when to update.
19+
20+### Core Concept
21+
22+**Store game state snapshots per in-game username (not per mysis):**
23+
24+- Mysis can switch accounts → state follows the account
25+- Each mysis has its own game account (SpaceMolt enforces one connection per account)
26+- State persists when mysis switches between different game accounts
27+- Account logout → clear that account's state
28+
29+**Include state in context with delta metadata:**
30+
31+```
32+Current Game State (updated 2 ticks ago):
33+ Player: VoidWanderer
34+ Credits: 5,000
35+ Location: Sol System > Asteroid Belt Alpha
36+ Ship: Cargo Hauler (Hull: 85%, Fuel: 60%)
37+ Cargo: 45/100 (Iron Ore x30, Copper Ore x15)
38+
39+To update: call get_status, get_ship, get_notifications
40+```
41+
42+**Benefits:**
43+
44+- 190 KB payload appears ONCE when first fetched
45+- Subsequent turns show compact summary with recency
46+- LLM knows "2 ticks ago" vs "50 ticks ago" → makes informed decisions
47+- State persists across mysis restarts
48+- No pollution when switching accounts
49+
50+## Architecture
51+
52+### Database Schema
53+
54+```sql
55+-- New table: game_state_snapshots
56+CREATE TABLE game_state_snapshots (
57+ id TEXT PRIMARY KEY,
58+ username TEXT NOT NULL, -- In-game username (e.g., "VoidWanderer")
59+ tool_name TEXT NOT NULL, -- Tool that produced this state (e.g., "get_status")
60+ content TEXT NOT NULL, -- Full JSON response from tool
61+ game_tick INTEGER, -- Game tick when captured (from response)
62+ captured_at INTEGER NOT NULL, -- Unix timestamp when stored
63+ UNIQUE(username, tool_name) -- One snapshot per tool per username
64+);
65+
66+CREATE INDEX idx_game_state_username ON game_state_snapshots(username);
67+```
68+
69+### State Lifecycle
70+
71+**1. Tool Call Interception**
72+
73+- When mysis calls `get_status`, `get_ship`, `get_map`, etc.
74+- After receiving response, extract username from result
75+- Store full response in `game_state_snapshots` table
76+- Upsert: replace old snapshot for this username+tool
77+
78+**2. Context Composition**
79+
80+- Before building LLM context, check if mysis has active game account
81+- If logged in, fetch all snapshots for that username
82+- Build compact state summary with recency metadata
83+- Include summary in system prompt or as synthetic user message
84+
85+**3. State Invalidation**
86+
87+- On `logout`: Delete all snapshots for that username
88+- On `register`: Create new username entry
89+- On `login`: Switch to existing username's snapshots
90+- On action (travel, mine, attack): Mark affected snapshots as stale
91+
92+### State Summary Format
93+
94+```markdown
95+## Current Game State
96+
97+**Account:** VoidWanderer (Solarian Empire)
98+**Last Updated:** 2 ticks ago (12 seconds)
99+
100+### Status (get_status - 2 ticks ago)
101+
102+- Credits: 5,000
103+- Location: Sol System > Asteroid Belt Alpha
104+- Ship: Cargo Hauler
105+- Docked: No
106+
107+### Ship (get_ship - 2 ticks ago)
108+
109+- Hull: 85/100
110+- Shield: 50/50
111+- Fuel: 60/100
112+- Cargo: 45/100
113+ - Iron Ore x30
114+ - Copper Ore x15
115+
116+### System (get_system - 5 ticks ago)
117+
118+- Sol System (Solarian Empire)
119+- POIs: Earth, Mars, Asteroid Belt Alpha, Station Alpha
120+- Connections: Alpha Centauri, Barnard's Star
121+
122+### Map (get_map - 50 ticks ago)
123+
124+- 487 systems cached
125+- Use get_map to refresh full galaxy data
126+
127+**Note:** Call get_notifications to see events since last update.
128+**Stale data:** get_map is 50 ticks old - consider refreshing if planning long journey.
129+```
130+
131+### Recency Calculation
132+
133+```go
134+type GameStateSnapshot struct {
135+ ToolName string
136+ Content string
137+ GameTick int // From game response
138+ CapturedAt time.Time // When we stored it
139+}
140+
141+func (s *GameStateSnapshot) RecencyMessage(currentTick int) string {
142+ if currentTick > 0 && s.GameTick > 0 {
143+ ticksAgo := currentTick - s.GameTick
144+ if ticksAgo == 0 {
145+ return "just now"
146+ }
147+ return fmt.Sprintf("%d ticks ago (%d seconds)", ticksAgo, ticksAgo*10)
148+ }
149+
150+ // Fallback to wall clock time
151+ elapsed := time.Since(s.CapturedAt)
152+ if elapsed < time.Minute {
153+ return fmt.Sprintf("%.0f seconds ago", elapsed.Seconds())
154+ }
155+ return fmt.Sprintf("%.0f minutes ago", elapsed.Minutes())
156+}
157+```
158+
159+## Implementation Plan
160+
161+### Phase 1: Database & Storage
162+
163+1. Add `game_state_snapshots` table to schema
164+2. Create `GameStateCache` struct in `internal/core/game_state.go`
165+3. Implement CRUD operations: Store, Get, Delete, List
166+
167+### Phase 2: Tool Interception
168+
169+1. Modify MCP proxy to intercept snapshot tool responses
170+2. Extract username from tool results (parse JSON)
171+3. Store snapshots in database with game tick
172+4. Handle login/logout/register to manage username association [Dont break exisitng account re-use logic!]
173+
174+### Phase 3: Context Integration
175+
176+1. Add `GetGameStateSummary(username)` method
177+2. Modify `getContextMemories()` to include state summary
178+3. Format summary with recency metadata
179+4. Add to system prompt or as synthetic message
180+
181+### Phase 4: Staleness Detection
182+
183+1. Track which actions invalidate which snapshots
184+2. Mark snapshots as "stale" after relevant actions
185+3. Prompt LLM to refresh stale data
186+4. Example: After `travel`, mark `get_status` as stale
187+
188+### Phase 5: Partial Updates
189+
190+1. Implement merge logic for partial state updates
191+2. Handle tools that return partial state (e.g., `get_notifications`)
192+3. Merge new data into existing snapshots without replacing entire snapshot
193+4. Track which fields were updated and when
194+
195+### Phase 6: Testing & Refinement
196+
197+1. Test with account switching (mysis changes between different game accounts)
198+2. Verify state persists across mysis restarts
199+3. Verify state isolation between different game accounts
200+4. Test partial update merging
201+5. Measure context size reduction
202+6. Tune staleness thresholds
203+
204+## Edge Cases
205+
206+### Account Switching (Single Mysis, Multiple Accounts)
207+
208+- Mysis logs out of Account A, logs into Account B
209+- Account A's state preserved in DB
210+- Account B's state loaded (or empty if new)
211+- No pollution between accounts
212+
213+### Stale Data After Actions
214+
215+- After `travel`: `get_status` location is stale
216+- After `mine`: `get_ship` cargo is stale
217+- After `buy`: `get_status` credits are stale
218+- Mark affected snapshots, prompt refresh
219+
220+### No Active Account
221+
222+- Mysis not logged in → no game state available
223+- Context shows: "Not logged in. Use register or login."
224+- After login, state appears
225+
226+### Tick Synchronization
227+
228+- Game tick comes from tool responses
229+- If tick not in response, fall back to wall clock time
230+- Recency still useful: "30 seconds ago" vs "5 minutes ago"
231+
232+## Expected Impact
233+
234+### Context Size Reduction
235+
236+- **Before:** 190 KB `get_map` every turn
237+- **After:** 190 KB once, then 2 KB summary per turn
238+- **Savings:** ~95% reduction in repeated data
239+
240+### Iteration Limit
241+
242+- **Before:** 10 iterations spent processing map data
243+- **After:** 1-2 iterations for decision making
244+- **Result:** Myses can complete multi-step plans
245+
246+### LLM Decision Quality
247+
248+- **Before:** "I don't know current state, better check"
249+- **After:** "State is 2 ticks old, still fresh, proceed"
250+- **Result:** More decisive, less redundant tool calls
251+
252+### State Persistence
253+
254+- Mysis restart → state preserved for its game account
255+- Account switch → correct state loaded for new account
256+- Each mysis operates independently with its own game account
257+- State keyed by username ensures proper isolation
258+
259+## Migration Path
260+
261+1. No backwards migration, new db required.
262+
263+## Success Metrics
264+
265+- **Tool call frequency:** Reduce `get_*` calls by 80%+
266+- **Iteration limits:** Reduce "Max tool iterations" warnings by 90%+
267+- **Context size:** Reduce average context from 191 KB to <20 KB
268+- **Decision speed:** Myses complete actions in 2-3 iterations vs 10
269+- **State accuracy:** LLMs make decisions with correct recency awareness
internal/mcp/client.go+8−0
@@ -82,6 +82,14 @@ func (c *Client) send(ctx context.Context, req *Request) (*Response, error) {
8282
8383 if httpResp.StatusCode != http.StatusOK {
8484 respBody, _ := io.ReadAll(httpResp.Body)
85+
86+ // For 429 rate limits, include Retry-After header if present
87+ if httpResp.StatusCode == http.StatusTooManyRequests {
88+ if retryAfter := httpResp.Header.Get("Retry-After"); retryAfter != "" {
89+ return nil, fmt.Errorf("http error %d: %s (Retry-After: %s)", httpResp.StatusCode, string(respBody), retryAfter)
90+ }
91+ }
92+
8593 return nil, fmt.Errorf("http error %d: %s", httpResp.StatusCode, string(respBody))
8694 }
8795
internal/mcp/proxy.go+49−1
@@ -5,6 +5,8 @@ import (
55 "encoding/json"
66 "errors"
77 "fmt"
8+ "regexp"
9+ "strconv"
810 "strings"
911 "sync"
1012 "time"
@@ -53,6 +55,37 @@ var (
5355 // Retry delays increased to respect SpaceMolt's "Try again in 5 seconds" rate limit
5456 var toolRetryDelays = []time.Duration{2 * time.Second, 5 * time.Second, 10 * time.Second}
5557
58+// retryAfterRegex matches "Retry-After: N" in error messages
59+var retryAfterRegex = regexp.MustCompile(`Retry-After:\s*(\d+)`)
60+
61+// parseRetryAfter extracts retry delay from error message containing "Retry-After: N seconds"
62+func parseRetryAfter(err error) (time.Duration, bool) {
63+ if err == nil {
64+ return 0, false
65+ }
66+
67+ errMsg := err.Error()
68+
69+ // Try to extract from "Retry-After: N" header format
70+ if matches := retryAfterRegex.FindStringSubmatch(errMsg); len(matches) > 1 {
71+ if seconds, parseErr := strconv.Atoi(matches[1]); parseErr == nil {
72+ return time.Duration(seconds) * time.Second, true
73+ }
74+ }
75+
76+ // Try to extract from "Try again in N seconds" message format
77+ if strings.Contains(errMsg, "Try again in") {
78+ re := regexp.MustCompile(`Try again in (\d+) seconds?`)
79+ if matches := re.FindStringSubmatch(errMsg); len(matches) > 1 {
80+ if seconds, parseErr := strconv.Atoi(matches[1]); parseErr == nil {
81+ return time.Duration(seconds) * time.Second, true
82+ }
83+ }
84+ }
85+
86+ return 0, false
87+}
88+
5689 // NewProxy creates a new MCP proxy.
5790 func NewProxy(upstream UpstreamClient) *Proxy {
5891 return &Proxy{
@@ -192,7 +225,22 @@ func (p *Proxy) callUpstreamWithRetry(ctx context.Context, name string, args int
192225 // Check if error is a 429 rate limit
193226 is429 := lastErr != nil && (strings.Contains(lastErr.Error(), "429") || strings.Contains(lastErr.Error(), "Rate limited"))
194227
195- if is429 {
228+ // Try to parse Retry-After from error message
229+ if retryAfter, ok := parseRetryAfter(lastErr); ok {
230+ // Use server-specified delay, but cap at 30 seconds for safety
231+ if retryAfter > 30*time.Second {
232+ retryAfter = 30 * time.Second
233+ }
234+ delay = retryAfter
235+
236+ log.Warn().
237+ Str("tool", name).
238+ Int("attempt", attempt).
239+ Dur("delay", delay).
240+ Dur("server_requested", retryAfter).
241+ Err(lastErr).
242+ Msg("MCP tool rate limited - respecting Retry-After")
243+ } else if is429 {
196244 log.Warn().
197245 Str("tool", name).
198246 Int("attempt", attempt).