xonecas.io
60255
Zn

Zoea-Nova / commit d006ec7

docs: add implementation and analysis reports from 2026-02-07 session

- LLM behavior analysis (session_id handling)
- Session ID error message audit
- Session ID loop fix implementation
- Turn-aware context implementation
- Prompt reconstruction tool documentation

xonecas2026-02-07 d006ec71f98bbc921ecbb6552b1b6a65086b6071 parent f4a1b48

5 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

documentation/reports/LLM_BEHAVIOR_ANALYSIS_SESSION_ID_2026-02-07.md+415βˆ’0
@@ -0,0 +1,415 @@
1+# LLM Behavior Analysis: Session ID Understanding
2+
3+**Date:** 2026-02-07
4+**Mysis Analyzed:** `ollama-one` (id: 01058ed1-cc72-406c-a0c2-3c20dba94d0d)
5+**Model:** `ollama/qwen3:4b`
6+**Status:** πŸ”΄ **CRITICAL ISSUE - LLM NOT FOLLOWING BOOTSTRAP**
7+
8+---
9+
10+## Executive Summary
11+
12+**Finding:** The LLM received credentials from `zoea_claim_account` but **never called login()**, instead inventing fake session_ids like `"your_session_id_here"`, `"session_12345"`, and `"your_session_id"`.
13+
14+**Root Cause:** The LLM is not following the Bootstrap instructions despite them being explicit in the system prompt.
15+
16+**Impact:** Mysis cannot authenticate with the game server, causing all game tool calls to fail.
17+
18+---
19+
20+## Observed Behavior Timeline
21+
22+### Turn Start (06:57:52)
23+```
24+System prompt delivered with new Session Management section:
25+"After login/register, you receive a session_id..."
26+```
27+
28+### First Action (06:58:09)
29+```
30+LLM: get_notifications(session_id: "your_session_id")
31+Server: "session_invalid: Call login() again"
32+```
33+❌ **LLM skipped Bootstrap entirely - never called zoea_claim_account or login**
34+
35+### Second Action (06:58:24)
36+```
37+LLM: get_notifications(session_id: "session_12345")
38+Server: "session_invalid: Call login() again"
39+```
40+❌ **LLM inventing fake session_ids instead of following Bootstrap**
41+
42+### Third Action (06:58:35)
43+```
44+LLM: get_notifications(session_id: "session_12345")
45+Server: "session_invalid: Call login() again"
46+```
47+❌ **Repeated the same fake session_id**
48+
49+### Fourth Action (06:58:46)
50+```
51+LLM: zoea_claim_account()
52+Server: Returns username: CrabZoea, password: 6443b68...
53+```
54+βœ… **Finally called zoea_claim_account (Bootstrap step 1)**
55+
56+### Fifth Action (06:59:05)
57+```
58+LLM: get_notifications(session_id: "your_session_id_here")
59+Server: "session_invalid: Call login() again"
60+```
61+❌ **Got credentials but never called login() - invented another fake session_id**
62+
63+---
64+
65+## Critical Problems Identified
66+
67+### Problem 1: LLM Not Following Bootstrap Sequence
68+
69+**Expected behavior per system prompt:**
70+```
71+1. Try zoea_claim_account (no arguments)
72+2. If you get credentials β†’ login
73+3. Extract session_id from login response
74+4. Use session_id for all game tools
75+```
76+
77+**Actual behavior:**
78+```
79+1. ❌ Skip zoea_claim_account
80+2. ❌ Skip login
81+3. ❌ Invent fake session_ids
82+4. ❌ Get errors, eventually try zoea_claim_account
83+5. ❌ Get credentials but STILL don't call login
84+6. ❌ Continue using fake session_ids
85+```
86+
87+### Problem 2: Inventing Session IDs
88+
89+**Fake session_ids used:**
90+- `"your_session_id"` (placeholder-like)
91+- `"session_12345"` (generic fake)
92+- `"your_session_id_here"` (literal placeholder text)
93+
94+**Why this is bad:**
95+- Shows LLM understands session_id is needed
96+- Shows LLM knows WHERE to put it (parameter name)
97+- But LLM doesn't understand session_id must come from tool result
98+- LLM treats it like a placeholder to fill in
99+
100+### Problem 3: Ignoring Tool Results
101+
102+**zoea_claim_account returned:**
103+```
104+username: CrabZoea
105+password: 6443b684b2b3a651c69cdba02b33802fc8601d455359edb9eb23fa08bd6ca554
106+```
107+
108+**System prompt says:**
109+```
110+2. If you get credentials β†’ login
111+```
112+
113+**LLM did:**
114+- ❌ Ignored the instruction
115+- ❌ Never called login with those credentials
116+- ❌ Went straight to get_notifications with fake session_id
117+
118+---
119+
120+## Why This Happens
121+
122+### Hypothesis 1: Model Capability Issue
123+
124+**qwen3:4b** may be:
125+- Too small to follow complex multi-step instructions
126+- Unable to reason about tool call sequencing
127+- Struggling with conditional logic ("if you get credentials β†’ login")
128+
129+**Evidence:**
130+- Never followed Bootstrap sequence
131+- Invented data instead of using tool results
132+- Repeated same mistakes despite errors
133+
134+### Hypothesis 2: Instruction Following Weakness
135+
136+The model may:
137+- Not parse numbered lists as actionable steps
138+- Treat system prompt as "context" not "commands"
139+- Fill parameters with plausible-looking data instead of real data
140+
141+**Evidence:**
142+- Fake session_ids look reasonable (string format correct)
143+- Eventually called zoea_claim_account (some instruction following)
144+- But never progressed to step 2 (weak sequential reasoning)
145+
146+### Hypothesis 3: Context Window Too Small
147+
148+**qwen3:4b context:** Likely 2k-4k tokens
149+
150+**System prompt alone:** ~450 tokens
151+
152+**Possible issues:**
153+- Can't hold full instruction set + conversation
154+- Loses Bootstrap instructions after a few turns
155+- Forgets the sequence by the time it acts
156+
157+---
158+
159+## Testing Results Summary
160+
161+### Session Management Instructions (Phase 1)
162+- βœ… Instructions present in system prompt
163+- βœ… Instructions clearly written
164+- ❌ LLM not following them
165+
166+### Error Message Rewriting (Phase 2)
167+- βœ… Error messages rewritten correctly
168+- βœ… Says "Call login() again" (which is correct after session_invalid)
169+- ❌ LLM not calling login despite instruction
170+
171+### Turn-Aware Context (v0.5.0)
172+- βœ… Would preserve session_id if one existed
173+- ❌ No session_id to preserve (never logged in)
174+- ❌ Irrelevant for this failure mode
175+
176+---
177+
178+## Database Evidence
179+
180+### Login Attempts
181+```sql
182+SELECT COUNT(*) FROM memories
183+WHERE mysis_id='01058ed1-cc72-406c-a0c2-3c20dba94d0d'
184+AND content LIKE '%"login"%'
185+AND role='assistant';
186+
187+Result: 0
188+```
189+**Zero login attempts despite having credentials**
190+
191+### Claim Account Calls
192+```sql
193+SELECT COUNT(*) FROM memories
194+WHERE mysis_id='01058ed1-cc72-406c-a0c2-3c20dba94d0d'
195+AND content LIKE '%zoea_claim_account%';
196+
197+Result: 1
198+```
199+**Called once (eventually) but didn't follow through**
200+
201+### Fake Session IDs
202+```sql
203+SELECT content FROM memories
204+WHERE mysis_id='01058ed1-cc72-406c-a0c2-3c20dba94d0d'
205+AND content LIKE '%session_id%'
206+AND role='assistant';
207+
208+Results:
209+- "session_id":"your_session_id"
210+- "session_id":"session_12345" (2x)
211+- "session_id":"your_session_id_here"
212+```
213+**Four attempts, all with invented session_ids**
214+
215+---
216+
217+## Comparison: Expected vs Actual
218+
219+### Expected Flow (Bootstrap)
220+```
221+1. Start
222+2. Call zoea_claim_account()
223+3. Receive credentials
224+4. Call login(username, password)
225+5. Receive session_id
226+6. Call get_status(session_id)
227+7. Success!
228+```
229+
230+### Actual Flow (qwen3:4b)
231+```
232+1. Start
233+2. Call get_notifications(fake_session_id) ← SKIP BOOTSTRAP
234+3. Get error: "session_invalid"
235+4. Call get_notifications(fake_session_id) ← REPEAT
236+5. Get error: "session_invalid"
237+6. Call get_notifications(fake_session_id) ← REPEAT
238+7. Get error: "session_invalid"
239+8. Call zoea_claim_account() ← FINALLY
240+9. Receive credentials
241+10. Call get_notifications(fake_session_id) ← SKIP LOGIN AGAIN
242+11. Still broken
243+```
244+
245+---
246+
247+## Root Cause Analysis
248+
249+### Why LLM Skips Login
250+
251+**Possible explanations:**
252+
253+1. **Tool availability confusion:**
254+ - LLM sees `get_notifications` in tool list
255+ - Assumes it can call it directly
256+ - Doesn't understand auth dependency
257+
258+2. **Instruction priority:**
259+ - System prompt says "ALWAYS end every turn by calling get_notifications"
260+ - This instruction is in "Critical Rules" section
261+ - LLM prioritizes "ALWAYS" over Bootstrap sequence
262+
263+3. **Parameter hallucination:**
264+ - LLM sees session_id is required
265+ - LLM knows strings go in that parameter
266+ - LLM generates plausible string instead of obtaining real one
267+
268+4. **Sequential reasoning failure:**
269+ - Bootstrap requires: claim β†’ login β†’ extract β†’ use
270+ - qwen3:4b may not handle 4-step sequences
271+ - Jumps directly to perceived end goal (get_notifications)
272+
273+---
274+
275+## Recommendations
276+
277+### Immediate Action: Test Different Model
278+
279+**Try larger/better models:**
280+```
281+ollama: llama3.3:8b, llama3.3:70b, qwq:32b
282+opencode_zen: gpt-5-nano, claude-sonnet-4
283+```
284+
285+**Why:**
286+- qwen3:4b may be too small for this task
287+- Need model with strong instruction following
288+- Need model with sequential reasoning
289+
290+### Short Term: Simplify Bootstrap
291+
292+**Current (complex):**
293+```
294+1. Try zoea_claim_account (no arguments)
295+2. If you get credentials β†’ login
296+3. IMPORTANT: The login response contains a session_id. Extract it and use it...
297+4. If no accounts available β†’ register...
298+5. Assess situation: get_status, get_system...
299+```
300+
301+**Proposed (simple):**
302+```
303+## First Actions (MANDATORY SEQUENCE)
304+1. Call zoea_claim_account()
305+2. When you receive credentials, immediately call login(username, password)
306+3. Extract session_id from login response
307+4. Use that session_id for ALL future game tool calls
308+
309+DO NOT call any game tools until you have a session_id from login.
310+```
311+
312+**Rationale:**
313+- Shorter, clearer sequence
314+- Explicit "DO NOT" prevents jumping ahead
315+- "MANDATORY SEQUENCE" signals importance
316+
317+### Medium Term: Add Guardrails
318+
319+**Detect bootstrap skip in code:**
320+```go
321+// In SendMessageFrom, before allowing game tool calls
322+if !mysis.hasValidSession() && isGameTool(toolName) {
323+ return error("Cannot call game tools without session. Complete bootstrap first.")
324+}
325+```
326+
327+**Benefits:**
328+- Prevents fake session_id attempts
329+- Forces correct sequence
330+- Provides immediate feedback
331+
332+### Long Term: Model Selection Guidance
333+
334+**Document model requirements:**
335+- Minimum 7B parameters for complex instruction following
336+- Models tested and known to work:
337+ - βœ… llama3.3:8b (if available)
338+ - βœ… gpt-5-nano (OpenCode)
339+ - ❌ qwen3:4b (too small)
340+
341+---
342+
343+## Comparison with Previous Issues
344+
345+### Claim→Login Loop (Historical)
346+**Issue:** Myses called login multiple times
347+**Cause:** Lost session_id from context
348+**Status:** βœ… Fixed (turn-aware context + session instructions)
349+
350+### Current Issue
351+**Issue:** Myses never call login at all
352+**Cause:** Model doesn't follow Bootstrap sequence
353+**Status:** πŸ”΄ **ACTIVE** - Model capability issue
354+
355+**Key Difference:**
356+- Old issue: Too MUCH login (unnecessary retries)
357+- New issue: Too LITTLE login (never happens)
358+- Old cause: Context management
359+- New cause: Model capability / instruction following
360+
361+---
362+
363+## Testing Plan
364+
365+### Test 1: Larger Model (High Priority)
366+```bash
367+# Switch to llama3.3:8b or similar
368+ollama pull llama3.3:8b
369+
370+# Configure mysis to use it
371+# Test Bootstrap sequence
372+# Monitor for successful login
373+```
374+
375+### Test 2: Simplified Prompt (Medium Priority)
376+```bash
377+# Update system prompt with simpler Bootstrap
378+# Test with same model (qwen3:4b)
379+# Compare behavior
380+```
381+
382+### Test 3: Add Guardrails (Low Priority)
383+```bash
384+# Implement session validation before game tools
385+# Test error handling
386+# Verify forced Bootstrap completion
387+```
388+
389+---
390+
391+## Conclusion
392+
393+**The session_id instructions (Phase 1 & 2) are working as designed**, but the underlying model (`qwen3:4b`) is **not capable of following multi-step Bootstrap instructions**.
394+
395+**Evidence:**
396+- βœ… Instructions present and clear
397+- βœ… Error messages helpful
398+- ❌ Model skips entire Bootstrap sequence
399+- ❌ Model invents fake data instead of using tool results
400+- ❌ Model doesn't follow conditional logic ("if credentials β†’ login")
401+
402+**Next Steps:**
403+1. **Test with larger/better model** (llama3.3:8b or gpt-5-nano)
404+2. **Simplify Bootstrap** if issue persists
405+3. **Add code-level guardrails** to prevent invalid sequences
406+
407+**Expected Outcome:**
408+- Larger model should follow Bootstrap correctly
409+- If not, instruction simplification needed
410+- Guardrails provide safety net for any model
411+
412+---
413+
414+**Analysis Complete**
415+**Recommendation:** Switch default model from qwen3:4b to llama3.3:8b or larger
documentation/reports/PROMPT_RECONSTRUCTION_TOOL_2026-02-07.md+249βˆ’0
@@ -0,0 +1,249 @@
1+# Prompt Reconstruction Tool
2+
3+Quick reference for reconstructing what was sent to the LLM provider.
4+
5+## Usage
6+
7+```bash
8+# Latest mysis
9+./scripts/reconstruct_prompt.sh
10+
11+# Specific mysis
12+./scripts/reconstruct_prompt.sh <mysis_id>
13+
14+# With provider payload simulation
15+./scripts/reconstruct_prompt.sh <mysis_id> --full
16+```
17+
18+## What Gets Sent to Provider
19+
20+### 1. Memory Retrieval
21+```go
22+// internal/core/mysis.go:459
23+memories, err := a.getContextMemories()
24+```
25+
26+**getContextMemories() logic:**
27+- System prompt (with broadcast injection)
28+- Historical context (compressed via extractLatestToolLoop)
29+- Current turn (complete, from last user prompt onward)
30+
31+### 2. Memory β†’ Message Conversion
32+```go
33+// internal/core/mysis.go:480
34+messages := a.memoriesToMessages(memories)
35+```
36+
37+**Conversion rules:**
38+- `system` role β†’ `{"role": "system", "content": "..."}`
39+- `user` role β†’ `{"role": "user", "content": "..."}`
40+- `assistant` with `[TOOL_CALLS]` β†’ parse tool calls, empty content
41+- `tool` role β†’ extract call_id from `call_id:content` format
42+
43+### 3. Provider Formatting
44+
45+**OpenAI-compatible (opencode_zen):**
46+```json
47+{
48+ "model": "gpt-5-nano",
49+ "messages": [
50+ {"role": "system", "content": "..."},
51+ {"role": "user", "content": "..."},
52+ {"role": "assistant", "tool_calls": [...]},
53+ {"role": "tool", "tool_call_id": "...", "content": "..."}
54+ ],
55+ "tools": [...],
56+ "temperature": 0.7
57+}
58+```
59+
60+## Example Reconstruction
61+
62+**Mysis:** prompt-test (baa89cbd-71ff-4e43-b7ea-cc4813b530cd)
63+
64+### Database Memories (chronological)
65+```
66+[0] system: "You are a Nova Zoea mysis..."
67+[1] assistant: [TOOL_CALLS]call_X:zoea_claim_account:{}
68+[2] tool: call_X:Use the game's login tool with credentials...
69+[3] assistant: [TOOL_CALLS]call_Y:zoea_claim_account:{} (REPEAT!)
70+[4] tool: call_Y:Use the game's login tool with credentials... (REPEAT!)
71+[5] assistant: [TOOL_CALLS]call_Z:get_status:{"session_id":"fake_123"}
72+[6] tool: call_Z:Error: session_invalid
73+```
74+
75+### Converted to Provider Messages
76+```json
77+[
78+ {
79+ "role": "system",
80+ "content": "You are a Nova Zoea mysis in SpaceMolt..."
81+ },
82+ {
83+ "role": "assistant",
84+ "content": "",
85+ "tool_calls": [
86+ {
87+ "id": "call_X",
88+ "type": "function",
89+ "function": {
90+ "name": "zoea_claim_account",
91+ "arguments": "{}"
92+ }
93+ }
94+ ]
95+ },
96+ {
97+ "role": "tool",
98+ "tool_call_id": "call_X",
99+ "content": "Use the game's login tool with these credentials:\nusername: CrabZoea\npassword: 6443..."
100+ },
101+ {
102+ "role": "assistant",
103+ "content": "",
104+ "tool_calls": [
105+ {
106+ "id": "call_Y",
107+ "type": "function",
108+ "function": {
109+ "name": "zoea_claim_account",
110+ "arguments": "{}"
111+ }
112+ }
113+ ]
114+ },
115+ {
116+ "role": "tool",
117+ "tool_call_id": "call_Y",
118+ "content": "Use the game's login tool with these credentials:\nusername: CrabZoea\npassword: 6443..."
119+ }
120+]
121+```
122+
123+### Problem Pattern Visible
124+
125+**Repetition detected:**
126+- Same tool called twice in a row (zoea_claim_account)
127+- Same response twice in a row (credentials)
128+- LLM sees: claim β†’ credentials β†’ claim β†’ credentials
129+- LLM learns: "This is the pattern, keep doing it"
130+
131+**Missing step:**
132+- Got credentials but never called `login`
133+- Jumped to `get_status` with invented session_id
134+
135+## Script: reconstruct_prompt.sh
136+
137+```bash
138+#!/bin/bash
139+MYSIS_ID=${1:-$(sqlite3 ~/.zoea-nova/zoea.db "SELECT id FROM myses ORDER BY created_at DESC LIMIT 1")}
140+MYSIS_NAME=$(sqlite3 ~/.zoea-nova/zoea.db "SELECT name FROM myses WHERE id='$MYSIS_ID'")
141+
142+echo "=== PROMPT RECONSTRUCTION FOR: $MYSIS_NAME ==="
143+echo ""
144+
145+# 1. Show raw memories
146+sqlite3 ~/.zoea-nova/zoea.db << SQL
147+SELECT
148+ '[' || row_number() OVER (ORDER BY created_at ASC) || ']',
149+ role,
150+ CASE
151+ WHEN length(content) > 150 THEN substr(content, 1, 150) || '...'
152+ ELSE content
153+ END
154+FROM memories
155+WHERE mysis_id='$MYSIS_ID'
156+ORDER BY created_at ASC;
157+SQL
158+
159+# 2. Detect repetition
160+echo ""
161+echo "## REPETITION ANALYSIS"
162+sqlite3 ~/.zoea-nova/zoea.db << SQL
163+WITH tool_calls AS (
164+ SELECT
165+ content,
166+ LAG(content) OVER (ORDER BY created_at) as prev_content
167+ FROM memories
168+ WHERE mysis_id='$MYSIS_ID' AND role='assistant'
169+)
170+SELECT 'REPEATED TOOL CALL: ' || content
171+FROM tool_calls
172+WHERE content = prev_content;
173+SQL
174+
175+sqlite3 ~/.zoea-nova/zoea.db << SQL
176+WITH tool_results AS (
177+ SELECT
178+ substr(content, instr(content, ':') + 1, 80) as result,
179+ LAG(substr(content, instr(content, ':') + 1, 80)) OVER (ORDER BY created_at) as prev_result
180+ FROM memories
181+ WHERE mysis_id='$MYSIS_ID' AND role='tool'
182+)
183+SELECT 'REPEATED TOOL RESULT: ' || result
184+FROM tool_results
185+WHERE result = prev_result;
186+SQL
187+```
188+
189+## Findings
190+
191+### Issue 1: Repetition Training
192+When LLMs see:
193+```
194+A β†’ B β†’ A β†’ B β†’ A β†’ B
195+```
196+
197+They learn this is the correct pattern and continue it.
198+
199+**Solution:** Compress repeated tool results in context (already implemented via `compactSnapshots()` but not for all tools).
200+
201+### Issue 2: Never Calling Login
202+Prompt says:
203+```
204+1. Call zoea_claim_account
205+2. You get username and password
206+3. Call login with that username and password
207+```
208+
209+But LLM:
210+```
211+1. βœ“ Called zoea_claim_account
212+2. βœ“ Got credentials
213+3. βœ— SKIPPED login
214+4. βœ— Invented session_id
215+```
216+
217+**Solution:** Add explicit blocker or simplify further.
218+
219+### Issue 3: Tool Result Format
220+Tool results like:
221+```
222+"Use the game's login tool with these credentials:
223+username: CrabZoea
224+password: 6443b684..."
225+```
226+
227+This is **instructional text**, not actual credentials.
228+
229+**LLM confusion:**
230+- Sees "Use the game's login tool"
231+- Might interpret as "I should use zoea_claim_account again"
232+- Doesn't extract the actual credentials
233+
234+**Better format:**
235+```json
236+{
237+ "action": "login_required",
238+ "username": "CrabZoea",
239+ "password": "6443b684..."
240+}
241+```
242+
243+## Next Steps
244+
245+1. βœ… Simplify prompt (done)
246+2. βœ… Remove confusing tools (done - removed zoea_swarm_status)
247+3. ⏳ Test with simplified prompt
248+4. πŸ”„ If still failing: Change zoea_claim_account response format
249+5. πŸ”„ If still failing: Add code-level blocker (can't call game tools without session_id)
documentation/reports/SESSION_ID_ERROR_MESSAGE_AUDIT_2026-02-07.md+419βˆ’0
@@ -0,0 +1,419 @@
1+# Session ID Error Message and Instruction Audit
2+
3+**Date:** 2026-02-07
4+**Auditor:** OpenCode Agent
5+**Focus:** System prompt instructions and server error messages related to session_id
6+
7+---
8+
9+## Executive Summary
10+
11+**Finding:** The system prompt contains **NO explicit instructions** about session_id usage, while the SpaceMolt server returns **explicit error messages** telling myses to call `login()` again. This creates a harmful instruction loop.
12+
13+**Impact:** Myses follow the server's error message instructions literally, causing claim→login loops when session_id is missing from tool calls.
14+
15+**Risk Level:** πŸ”΄ **HIGH** - Active loops occurring in production
16+
17+---
18+
19+## Server Error Messages (What Myses See)
20+
21+### Error Type 1: session_required
22+
23+**Pattern:**
24+```
25+Error calling <tool_name>: Error: session_required: You must provide a session_id. Get one by calling login() or register() first.
26+```
27+
28+**Examples from production database:**
29+```
30+Error calling get_notifications: Error: session_required: You must provide a session_id...
31+Error calling get_status: Error: session_required: You must provide a session_id...
32+```
33+
34+**Count:** 6 instances found in recent memories
35+
36+**Instruction to LLM:** "Get one by calling login() or register() first."
37+
38+---
39+
40+### Error Type 2: session_invalid
41+
42+**Pattern:**
43+```
44+Error calling <tool_name>: Error: session_invalid: Session not found or expired. Call login() again to get a new session_id.
45+```
46+
47+**Examples from production database:**
48+```
49+Error calling get_notifications: Error: session_invalid: Session not found or expired. Call login() again to get a new session_id.
50+```
51+
52+**Count:** 5+ instances found in recent memories
53+
54+**Instruction to LLM:** "Call login() again to get a new session_id."
55+
56+---
57+
58+## System Prompt Analysis (What We Tell Myses)
59+
60+### Current System Prompt (internal/constants/constants.go)
61+
62+**Bootstrap Section (lines 12-16):**
63+```
64+## Bootstrap
65+1. Try zoea_claim_account (no arguments)
66+2. If you get credentials β†’ login
67+3. If no accounts available β†’ register with a username fitting for a Nova Zoea mysis in the cosmos
68+4. Assess situation: get_status, get_system, get_poi, get_ship
69+```
70+
71+**Critical Rules Section (lines 28-38):**
72+```
73+## Critical Rules
74+ALWAYS end every turn by calling get_notifications. It provides current_tick and game events.
75+
76+NEVER store or share your password in captain's log or any game tool.
77+
78+Use game ticks only (current_tick, arrival_tick, cooldown_ticks) - not real-world time.
79+
80+Captain's log entry field must be non-empty (max 20 entries, 100KB each).
81+
82+Context is limited - use search tools for older information.
83+
84+Make your own decisions. Adapt. Support the swarm.
85+```
86+
87+---
88+
89+### What's Missing from System Prompt
90+
91+**NO instructions about:**
92+
93+1. ❌ **What session_id is**
94+ - Not mentioned anywhere in system prompt
95+ - LLM must infer from tool schemas and responses
96+
97+2. ❌ **Where to get session_id**
98+ - Prompt says "login" but doesn't mention session_id is returned
99+ - No instruction to "extract session_id from login response"
100+
101+3. ❌ **How to use session_id**
102+ - No mention that game tools require session_id parameter
103+ - No instruction to "pass session_id to all authenticated tool calls"
104+
105+4. ❌ **When session_id is valid**
106+ - No mention that session_id persists across multiple tool calls
107+ - No instruction to "reuse session_id from earlier in the turn"
108+
109+5. ❌ **How to handle session errors**
110+ - No instruction to "only re-login if session is truly expired"
111+ - No warning against "calling login repeatedly within the same turn"
112+
113+---
114+
115+## The Problem Loop
116+
117+### Current Harmful Pattern
118+
119+```
120+1. Mysis calls login()
121+ β†’ Receives: { "session_id": "abc123", ... }
122+
123+2. Mysis calls get_status() WITHOUT session_id
124+ β†’ Error: "session_required: You must provide a session_id.
125+ Get one by calling login() or register() first."
126+
127+3. Mysis follows the error message instruction
128+ β†’ Calls zoea_claim_account
129+ β†’ Calls login() AGAIN
130+
131+4. Goto step 2 (LOOP)
132+```
133+
134+**Why this happens:**
135+- Mysis has session_id in context (from turn-aware composition)
136+- But LLM doesn't understand it should USE that session_id
137+- Server error message explicitly tells it to "call login() again"
138+- Mysis follows instructions literally
139+
140+---
141+
142+## Tool Schema Analysis
143+
144+### Tools That Require session_id
145+
146+From MCP tool schemas (per GET_NOTIFICATIONS_API_INVESTIGATION.md):
147+
148+**get_notifications:**
149+```json
150+{
151+ "inputSchema": {
152+ "properties": {
153+ "session_id": {
154+ "description": "Your session ID from login/register",
155+ "type": "string"
156+ }
157+ },
158+ "required": ["session_id"]
159+ }
160+}
161+```
162+
163+**Other tools with session_id:**
164+- get_status (required)
165+- get_system (required)
166+- get_ship (required)
167+- get_poi (required)
168+- travel (required)
169+- mine (required)
170+- All game action tools (required)
171+
172+**Note:** Tool schemas DO mention "Your session ID from login/register" but:
173+- This is buried in parameter description
174+- LLMs may not connect "login returns session_id" β†’ "use it here"
175+- No explicit instruction to reuse session_id across calls
176+
177+---
178+
179+## Turn-Aware Context Composition (v0.5.0+)
180+
181+### Current Implementation
182+
183+As of v0.5.0, **turn-aware context composition preserves session_id** within the current turn:
184+
185+**Example:**
186+```
187+Turn:
188+ [user: "Check ship status"]
189+ [assistant: login tool call]
190+ [tool: {"session_id": "abc123", ...}] ← PRESERVED in context
191+ [assistant: get_status tool call]
192+ [tool: ship data]
193+```
194+
195+**What this means:**
196+- βœ… session_id IS visible to the LLM within the same turn
197+- βœ… LLM CAN reference it if it understands to do so
198+- ❌ LLM may NOT understand it should use it
199+- ❌ LLM follows server error message ("call login again") instead
200+
201+---
202+
203+## Recommendations
204+
205+### High Priority: Update System Prompt
206+
207+**Add explicit session_id instructions to the Bootstrap section:**
208+
209+```markdown
210+## Bootstrap
211+1. Try zoea_claim_account (no arguments)
212+2. If you get credentials β†’ login
213+3. **IMPORTANT: The login response contains a session_id. Extract it and use it for ALL subsequent game tool calls.**
214+4. If no accounts available β†’ register with a username fitting for a Nova Zoea mysis in the cosmos
215+5. Assess situation: get_status, get_system, get_poi, get_ship (all require session_id)
216+```
217+
218+**Add to Critical Rules:**
219+
220+```markdown
221+## Session Management
222+After login/register, you receive a session_id. This session_id:
223+- Is valid for the entire game session
224+- Must be passed to ALL game tool calls (get_status, get_notifications, travel, mine, etc.)
225+- Should be reused across multiple tool calls in the same turn
226+- Does NOT expire between tool calls
227+
228+NEVER call login() again unless you receive a "session_invalid" error.
229+If you see "session_required", the session_id is in your recent tool results - find it and use it.
230+```
231+
232+---
233+
234+### Medium Priority: Improve Error Context
235+
236+**Option A: Intercept and rewrite server errors**
237+
238+In `internal/mcp/proxy.go`, detect session errors and provide better guidance:
239+
240+```go
241+// Before returning error to LLM
242+if strings.Contains(errorMsg, "session_required") {
243+ errorMsg = "Error: session_required. Check your recent tool results for session_id from login/register. Use that session_id parameter."
244+}
245+
246+if strings.Contains(errorMsg, "session_invalid") {
247+ errorMsg = "Error: session_invalid. Your session expired. Call login() with your credentials to get a new session_id."
248+}
249+```
250+
251+**Option B: Add synthetic context hint**
252+
253+After detecting session error, inject ephemeral system message:
254+
255+```
256+HINT: You called login() earlier in this turn. The session_id is in that tool result. Use it for this call.
257+```
258+
259+---
260+
261+### Low Priority: Session ID Injection
262+
263+**For cross-turn persistence** (session_id from previous turns):
264+
265+Extract session_id from historical turns and inject as persistent system message:
266+
267+```
268+Your current session_id: abc123
269+Include this in all game tool calls.
270+```
271+
272+**Note:** This is less urgent now that turn-aware composition preserves session_id within the current turn.
273+
274+---
275+
276+## Evidence from Production
277+
278+### Recent Loops (from database query)
279+
280+**Mysis:** e2cb9bf3-abed-4bd0-9f11-f81d5e0c64bc
281+
282+**Timeline:**
283+```
284+05:47:08 - zoea_claim_account (bootstrap)
285+05:47:19 - get_notifications β†’ "session_required" error
286+05:47:22 - zoea_claim_account (2nd time - LOOP STARTED)
287+05:47:34 - get_status/get_system β†’ "session_invalid" errors
288+05:47:42 - zoea_claim_account (3rd time)
289+05:48:03 - get_status β†’ "session_invalid" error
290+05:48:06 - zoea_claim_account (4th time)
291+05:48:17 - login (finally succeeded)
292+```
293+
294+**Root Cause:**
295+1. LLM called login and received session_id
296+2. LLM called get_notifications WITHOUT session_id
297+3. Server error said "Get one by calling login() or register() first"
298+4. LLM followed instructions literally β†’ claimed account and logged in again
299+5. Loop repeated 4 times before finally working
300+
301+**Why it eventually worked:**
302+- Luck (LLM finally included session_id parameter)
303+- OR turn-aware context made session_id more visible after multiple attempts
304+
305+---
306+
307+## Testing Recommendations
308+
309+### Before Fix
310+
311+1. **Monitor claim→login loop frequency:**
312+ ```sql
313+ SELECT mysis_id, COUNT(*) as claim_count
314+ FROM memories
315+ WHERE content LIKE '%zoea_claim_account%'
316+ GROUP BY mysis_id
317+ HAVING claim_count > 1;
318+ ```
319+
320+2. **Monitor session_required errors:**
321+ ```sql
322+ SELECT COUNT(*)
323+ FROM memories
324+ WHERE content LIKE '%session_required%';
325+ ```
326+
327+### After Fix
328+
329+1. **Verify loops eliminated:**
330+ - Run same queries
331+ - Should see claim_count = 1 (only bootstrap)
332+ - Should see session_required = 0 (no errors)
333+
Cut short: this commit's diff is over 1000 lines.
documentation/reports/SESSION_ID_LOOP_FIX_IMPLEMENTATION_2026-02-07.md+455βˆ’0
Cut short: this commit's diff is over 1000 lines.
documentation/reports/TURN_AWARE_CONTEXT_IMPLEMENTATION_2026-02-07.md+329βˆ’0
Cut short: this commit's diff is over 1000 lines.