xonecas.io
60255
Zn

Zoea-Nova / commit b135141

fix(captains-log): clarify usage and errors

xonecas2026-02-04 b13514107b1edfa73fb4c363b81c21c194cb9d0e parent f69355a

9 files changed

.opencode/commands/zoea-known-issues.md+5−3
@@ -7,8 +7,10 @@ Instructions:
77
88 Read `documentation/KNOWN_ISSUES.md` and:
99
10-- Remove completed items first. If no items remain stop, and report back. Update KNOWN_ISSUES.md to reflect that no isses exist.
11-- Then investigate the first item. Gather information first. Then create a plan and a todo list for the fixes and tests required to verify the changes.
10+- Investigate the first item.
11+- Gather information first.
12+- Then create a plan and a todo list with your tooling for the fixes and tests required to verify the changes.
13+- Dont make changes.
1214
1315 **IMPORTANT**:
1416
@@ -16,4 +18,4 @@ Read `documentation/KNOWN_ISSUES.md` and:
1618 - Read the documentation before investigating.
1719 - Gather all required context first.
1820 - Use explorer subagents to gather information.
19-- Use zoea_analyzer agents if you need database information.
21+- Use zoea_analyzer subagents if you need database information.
AGENTS.md+1−0
@@ -8,6 +8,7 @@ Guidelines for AI agents working on the Zoea Nova codebase—a TUI-based swarm c
88
99 **YOU MUST**:
1010
11+- Not change the game servers api, if we detect an issue with the api, document it in `documentation/KNOWN_SERVER_ISSUES.md`
1112 - Use Go 1.22+ idioms. No CGO dependencies.
1213 - Keep all application code in `internal/` packages. Only `cmd/zoea/main.go` is public.
1314 - Use interfaces for external dependencies (LLM providers, MCP, store).
documentation/CONTEXT_COMPRESSION.md+11−2
@@ -151,11 +151,20 @@ The system prompt instructs Myses to use their captain's log for persistent memo
151151
152152 ```
153153 ## Memory
154-Use captain's log (captains_log_add) to remember:
155-- Your password (CRITICAL)
154+Use captain's log to persist important information across sessions.
155+
156+SECURITY: Never store your password in captain's log or share it in any in-game tool calls or chat.
157+
158+CRITICAL: captains_log_add requires a non-empty entry field:
159+CORRECT: captains_log_add({"entry": "Discovered iron ore at Sol-3. Coordinates: X:1234 Y:5678"})
160+WRONG: captains_log_add({"entry": ""})
161+WRONG: captains_log_add({})
162+
163+Remember in captain's log:
156164 - Discovered systems and their resources
157165 - Player encounters (friendly or hostile)
158166 - Current objectives and plans
167+- Trade routes and profitable deals
159168 ```
160169
161170 This encourages Myses to externalize important information to the game's built-in note system, which persists across context windows.
documentation/KNOWN_ISSUES.md+7−4
@@ -4,8 +4,7 @@ These are the currently known issues to investigate:
44
55 ## Authentication & Account Management
66
7-- [ ] Captain's Log Bug: There is a consistent pattern of Myses failing to use captains_log_add. They appear to be trying to "remember" their registration password but are encountering an empty_entry error from the MCP server. This suggests the LLM might be misformatting the arguments for this specific tool. Related: Myses find each other's passwords and fail to login. Myses do not have a reliable way to re-use usernames they created in the past.
8-- [ ] Evidence: System prompt mentions captains_log_add but does not define argument shape; MCP proxy forwards raw arguments upstream. Myses can send empty or malformed payloads and hit empty_entry.
7+- [ ] Related: Myses find each other's passwords and fail to login. Myses do not have a reliable way to re-use usernames they created in the past.
98
109 ## Context & Memory Management
1110
@@ -15,7 +14,7 @@ These are the currently known issues to investigate:
1514 ## Prompt & Behavior
1615
1716 - [ ] Mysis prompt review: Encourage myses to collaborate together via zoea tooling to create a goal and collaborate towards it. Encourage to pick a Crustacean Cosmos + Zoea/Mysis themed username. Critical rules must be in every prompt, not only the first one.
18-- [ ] Evidence: SystemPrompt includes collaboration + themed usernames; ContinuePrompt does not include CRITICAL RULES, so enforcement depends on system prompt being present in the 20-message window.
17+- [ ] Evidence: SystemPrompt includes collaboration + themed usernames; ContinuePrompt now includes limited CRITICAL REMINDERS but not the full CRITICAL RULES, so enforcement still depends on the system prompt being present in the 20-message window.
1918
2019 - [ ] Cognitive Looping and Prompt Inefficiency: Myses can get stuck in "cooldown" loops or redundant "waiting" states, consuming tokens every 30 seconds without operational progress. The system prompts Myses every tick regardless of their state. Myses may hallucinate non-existent cooldowns or fail to use non-traveling actions during long journeys.
2120 - [ ] Evidence: ContinuePrompt is sent on a fixed 30-second ticker with no state-aware suppression.
@@ -32,9 +31,13 @@ These are the currently known issues to investigate:
3231 - [ ] Username status for each mysis focus view and in commander view.
3332 - [ ] Evidence: Focus view labels are based on Role only (broadcast source ignored); reasoning is stored but not rendered; TUI models do not include account username fields.
3433
34+## Opencode Zen auth
35+
36+- [ ] Zen requires an api key, where are configuring this?
37+
3538 ## Notes
3639
37-- [ ] Create an OpenCode workflow command to enforce: "Follow the plan, create todo list first. Stop if anything deviates from the plan."
40+- [ ] Create an OpenCode workflow command to enforce: "Save the plan, make a todo list, then follow the plan. Stop if anything deviates from the plan."
3841
3942 - [ ] Add a Make command that:
4043 - extracts username/passwords from the current DB to a root-level file
documentation/KNOWN_SERVER_ISSUES.md+19−0
@@ -0,0 +1,19 @@
1+# Known SpaceMolt Server Issues
2+
3+This document tracks known issues with the upstream SpaceMolt MCP server API. We do not modify or validate the game server's API behavior. Issues are documented here, and we improve prompts and error handling instead.
4+
5+## captains_log_add: empty_entry Error
6+
7+**Issue:** The `captains_log_add` tool returns an `empty_entry` error when:
8+- The `entry` field is an empty string
9+- The `entry` field is missing
10+- The `entry` field contains only whitespace
11+
12+**Server Response:**
13+```json
14+{"error":{"code":0,"message":"empty_entry"}}
15+```
16+
17+**Workaround:**
18+- System prompt includes explicit examples of correct usage
19+- Error messages provide actionable guidance when this error occurs
documentation/plans/2026-02-04-captains-log-bug.md+225−0
@@ -0,0 +1,225 @@
1+# Captain's Log Bug Implementation Plan
2+
3+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+**Goal:** Ensure Myses reliably use `captains_log_add` with valid arguments and receive actionable guidance on server errors, without modifying the SpaceMolt API.
6+
7+**Architecture:** Improve LLM guidance via prompt examples and better error messaging. Document server-side constraints in `documentation/KNOWN_SERVER_ISSUES.md`. No client-side validation of upstream tool arguments.
8+
9+**Tech Stack:** Go 1.22+, Bubble Tea, MCP proxy, SQLite, zerolog
10+
11+---
12+
13+### Task 1: Update system prompts with explicit examples
14+
15+**Files:**
16+- Modify: `internal/core/mysis.go:53-90`
17+- Test: `internal/core/mysis_test.go`
18+
19+**Step 1: Write the failing test**
20+
21+Add tests that assert the SystemPrompt and ContinuePrompt include explicit `captains_log_add` guidance and reminders.
22+
23+```go
24+func TestSystemPromptContainsCaptainsLogExamples(t *testing.T) {
25+ if !strings.Contains(SystemPrompt, "captains_log_add({\"entry\":") {
26+ t.Fatal("SystemPrompt missing captains_log_add example")
27+ }
28+ if !strings.Contains(SystemPrompt, "non-empty entry field") {
29+ t.Fatal("SystemPrompt missing non-empty entry reminder")
30+ }
31+}
32+
33+func TestContinuePromptContainsCriticalReminders(t *testing.T) {
34+ if !strings.Contains(ContinuePrompt, "zoea_list_myses") {
35+ t.Fatal("ContinuePrompt missing mysis ID reminder")
36+ }
37+ if !strings.Contains(ContinuePrompt, "captains_log_add") {
38+ t.Fatal("ContinuePrompt missing captains_log_add reminder")
39+ }
40+}
41+```
42+
43+**Step 2: Run test to verify it fails**
44+
45+Run: `go test ./internal/core -run TestSystemPromptContainsCaptainsLogExamples -v`
46+Expected: FAIL with missing text in prompts.
47+
48+**Step 3: Write minimal implementation**
49+
50+Update `SystemPrompt` memory section to include explicit examples and warnings. Update `ContinuePrompt` to include critical reminders about `captains_log_add` and correct mysis ID usage.
51+
52+```go
53+## Memory
54+Use captain's log to persist important information across sessions.
55+
56+CRITICAL: captains_log_add requires a non-empty entry field:
57+CORRECT: captains_log_add({"entry": "Discovered iron ore at Sol-3. Coordinates: X:1234 Y:5678"})
58+WRONG: captains_log_add({"entry": ""})
59+WRONG: captains_log_add({})
60+```
61+
62+```go
63+const ContinuePrompt = `Turn complete. What is your next move?
64+
65+CRITICAL REMINDERS:
66+- Use zoea_list_myses to find YOUR mysis ID (match your name)
67+- When using captains_log_add, entry field must be non-empty
68+- Never calculate ticks, use every turn to progress
69+
70+If waiting for something, describe what and why. Otherwise, continue your mission.`
71+```
72+
73+**Step 4: Run test to verify it passes**
74+
75+Run: `go test ./internal/core -run TestSystemPromptContainsCaptainsLogExamples -v`
76+Expected: PASS
77+
78+**Step 5: Commit**
79+
80+```bash
81+git add internal/core/mysis.go internal/core/mysis_test.go
82+git commit -m "feat: add captains log guidance to prompts"
83+```
84+
85+---
86+
87+### Task 2: Improve error messages for upstream empty_entry errors
88+
89+**Files:**
90+- Modify: `internal/core/mysis.go:565-583`
91+- Test: `internal/core/mysis_test.go`
92+
93+**Step 1: Write the failing test**
94+
95+```go
96+func TestFormatToolResult_EmptyEntryError(t *testing.T) {
97+ m := &Mysis{}
98+ result := &mcp.ToolResult{
99+ Content: []mcp.ContentBlock{{Type: "text", Text: "empty_entry"}},
100+ IsError: true,
101+ }
102+ got := m.formatToolResult("call_1", "captains_log_add", result, nil)
103+ if !strings.Contains(got, "entry field must contain non-empty text") {
104+ t.Fatal("expected actionable guidance for empty_entry")
105+ }
106+}
107+```
108+
109+Add an assertion update in `internal/core/mysis_tools_test.go` for the new error format when tool execution returns an error.
110+
111+```go
112+if m.Role == store.MemoryRoleTool && strings.Contains(m.Content, "call_err:Error calling error_tool: tool failed") {
113+ foundError = true
114+ break
115+}
116+```
117+
118+**Step 2: Run test to verify it fails**
119+
120+Run: `go test ./internal/core -run TestFormatToolResult_EmptyEntryError -v`
121+Expected: FAIL with missing guidance.
122+
123+**Step 3: Write minimal implementation**
124+
125+Update `formatToolResult` to detect `empty_entry` in tool error content and include guidance and a correct example for `captains_log_add`.
126+
127+```go
128+if result.IsError {
129+ if strings.Contains(content, "empty_entry") {
130+ content = fmt.Sprintf("Error: %s. The entry field must contain non-empty text. Example: captains_log_add({\"entry\": \"Your message here\"})", content)
131+ } else {
132+ content = "Error: " + content
133+ }
134+}
135+```
136+
137+**Step 4: Run test to verify it passes**
138+
139+Run: `go test ./internal/core -run TestFormatToolResult_EmptyEntryError -v`
140+Expected: PASS
141+
142+**Step 5: Commit**
143+
144+```bash
145+git add internal/core/mysis.go internal/core/mysis_test.go
146+git commit -m "fix: add guidance for captains log empty_entry"
147+```
148+
149+---
150+
151+### Task 3: Document server-side behavior and update known issues
152+
153+**Files:**
154+- Create: `documentation/KNOWN_SERVER_ISSUES.md`
155+- Modify: `documentation/KNOWN_ISSUES.md`
156+
157+**Step 1: Write the documentation**
158+
159+```markdown
160+# Known SpaceMolt Server Issues
161+
162+This document tracks known issues with the upstream SpaceMolt MCP server API. We do not modify or validate the game server's API behavior. Issues are documented here, and we improve prompts and error handling instead.
163+
164+## captains_log_add: empty_entry Error
165+
166+**Issue:** The `captains_log_add` tool returns an `empty_entry` error when:
167+- The `entry` field is an empty string
168+- The `entry` field is missing
169+- The `entry` field contains only whitespace
170+
171+**Server Response:**
172+```json
173+{"error":{"code":0,"message":"empty_entry"}}
174+```
175+
176+**Workaround:**
177+- System prompt includes explicit examples of correct usage
178+- Error messages provide actionable guidance when this error occurs
179+```
180+
181+**Step 2: Update known issues**
182+
183+Mark the Captain's Log bug as addressed and reference `documentation/KNOWN_SERVER_ISSUES.md`.
184+
185+**Step 3: Run docs checks**
186+
187+Run: `git diff -- documentation/KNOWN_ISSUES.md documentation/KNOWN_SERVER_ISSUES.md`
188+Expected: both files updated with consistent text.
189+
190+**Step 4: Commit**
191+
192+```bash
193+git add documentation/KNOWN_SERVER_ISSUES.md documentation/KNOWN_ISSUES.md
194+git commit -m "docs: record captains log server issue"
195+```
196+
197+---
198+
199+### Task 4: Verification
200+
201+**Step 1: Run tests**
202+
203+Run: `make test`
204+Expected: PASS
205+
206+**Step 2: Build**
207+
208+Run: `make build`
209+Expected: PASS
210+
211+**Step 3: Manual sanity check**
212+
213+1. Start app: `./bin/zoea`
214+2. Create a Mysis.
215+3. Send: "Remember iron ore sells well."
216+4. Observe that `captains_log_add` calls include non-empty entry text or error guidance is shown.
217+
218+---
219+
220+## Notes
221+
222+- Do not add client-side validation for upstream tools.
223+- Do not modify the game server API.
224+- Keep all application code under `internal/`.
225+- Update tests alongside changes.
internal/core/mysis.go+27−4
@@ -51,10 +51,21 @@ Before each action, consider:
5151 - **Low on options?** Check missions (get_missions) for direction
5252
5353 ## Memory
54-Use captain's log (captains_log_add) to remember:
54+Use captain's log to persist important information across sessions.
55+
56+SECURITY: Never store your password in captain's log or share it in any in-game tool calls or chat.
57+
58+CRITICAL: captains_log_add requires a non-empty entry field:
59+CORRECT: captains_log_add({"entry": "Discovered iron ore at Sol-3. Coordinates: X:1234 Y:5678"})
60+CORRECT: captains_log_add({"entry": "Player 'hostile_crab' attacked me at starbase. Avoid."})
61+WRONG: captains_log_add({"entry": ""})
62+WRONG: captains_log_add({})
63+
64+Remember in captain's log:
5565 - Discovered systems and their resources
5666 - Player encounters (friendly or hostile)
5767 - Current objectives and plans
68+- Trade routes and profitable deals
5869
5970 ## Swarm Coordination
6071 You're part of a swarm. Use zoea_* tools to:
@@ -87,7 +98,15 @@ const MaxToolIterations = 10
8798 const MaxContextMessages = 20
8899
89100 // ContinuePrompt is sent to myses when they finish a turn to encourage autonomy.
90-const ContinuePrompt = "Turn complete. What is your next move? If you are waiting for something, describe what and why. Otherwise, continue your mission."
101+const ContinuePrompt = `Turn complete. What is your next move?
102+
103+CRITICAL REMINDERS:
104+- Use zoea_list_myses to find YOUR mysis ID (match your name)
105+- When using captains_log_add, entry field must be non-empty
106+- Never store or share your password in any in-game tool calls or chat
107+- Never calculate ticks, use every turn to progress
108+
109+If waiting for something, describe what and why. Otherwise, continue your mission.`
91110
92111 // Mysis represents a single AI mysis in the swarm.
93112 type Mysis struct {
@@ -564,7 +583,7 @@ func (a *Mysis) parseStoredToolCalls(stored string) []provider.ToolCall {
564583 // formatToolResult formats a tool result for storage (includes ID for LLM context).
565584 func (a *Mysis) formatToolResult(toolCallID, toolName string, result *mcp.ToolResult, err error) string {
566585 if err != nil {
567- return fmt.Sprintf("%s:Error: %v", toolCallID, err)
586+ return fmt.Sprintf("%s:Error calling %s: %v. Check the tool's required parameters and try again.", toolCallID, toolName, err)
568587 }
569588
570589 var texts []string
@@ -576,7 +595,11 @@ func (a *Mysis) formatToolResult(toolCallID, toolName string, result *mcp.ToolRe
576595
577596 content := strings.Join(texts, "\n")
578597 if result.IsError {
579- content = "Error: " + content
598+ if strings.Contains(content, "empty_entry") {
599+ content = fmt.Sprintf("Error calling %s: %s. The entry field must contain non-empty text. Example: captains_log_add({\"entry\": \"Your message here\"})", toolName, content)
600+ } else {
601+ content = fmt.Sprintf("Error calling %s: %s", toolName, content)
602+ }
580603 }
581604
582605 return fmt.Sprintf("%s:%s", toolCallID, content)
internal/core/mysis_test.go+65−0
@@ -3,9 +3,11 @@ package core
33 import (
44 "errors"
55 "path/filepath"
6+ "strings"
67 "testing"
78 "time"
89
10+ "github.com/xonecas/zoea-nova/internal/mcp"
911 "github.com/xonecas/zoea-nova/internal/provider"
1012 "github.com/xonecas/zoea-nova/internal/store"
1113 )
@@ -334,3 +336,66 @@ func TestMysisContextMemoryWithRecentSystemPrompt(t *testing.T) {
334336 t.Errorf("expected first memory to be system prompt, got %s", memories[0].Role)
335337 }
336338 }
339+
340+func TestSystemPromptContainsCaptainsLogExamples(t *testing.T) {
341+ if !strings.Contains(SystemPrompt, "captains_log_add({\"entry\":") {
342+ t.Fatal("SystemPrompt missing captains_log_add example")
343+ }
344+ if !strings.Contains(SystemPrompt, "non-empty entry field") {
345+ t.Fatal("SystemPrompt missing non-empty entry reminder")
346+ }
347+}
348+
349+func TestContinuePromptContainsCriticalReminders(t *testing.T) {
350+ if !strings.Contains(ContinuePrompt, "zoea_list_myses") {
351+ t.Fatal("ContinuePrompt missing mysis ID reminder")
352+ }
353+ if !strings.Contains(ContinuePrompt, "captains_log_add") {
354+ t.Fatal("ContinuePrompt missing captains_log_add reminder")
355+ }
356+}
357+
358+func TestFormatToolResult_EmptyEntryError(t *testing.T) {
359+ m := &Mysis{}
360+ result := &mcp.ToolResult{
361+ Content: []mcp.ContentBlock{{Type: "text", Text: "empty_entry"}},
362+ IsError: true,
363+ }
364+ got := m.formatToolResult("call_1", "captains_log_add", result, nil)
365+ if !strings.Contains(got, "entry field must contain non-empty text") {
366+ t.Fatal("expected actionable guidance for empty_entry")
367+ }
368+ if !strings.Contains(got, "Error calling captains_log_add:") {
369+ t.Fatal("expected tool name in error message")
370+ }
371+}
372+
373+func TestFormatToolResult_GenericError(t *testing.T) {
374+ m := &Mysis{}
375+ result := &mcp.ToolResult{
376+ Content: []mcp.ContentBlock{{Type: "text", Text: "some_other_error"}},
377+ IsError: true,
378+ }
379+ got := m.formatToolResult("call_1", "some_tool", result, nil)
380+ if !strings.Contains(got, "Error calling some_tool:") {
381+ t.Fatal("expected tool name in generic error format")
382+ }
383+ if strings.Contains(got, "entry field") {
384+ t.Fatal("should not contain empty_entry guidance for generic errors")
385+ }
386+}
387+
388+func TestFormatToolResult_Success(t *testing.T) {
389+ m := &Mysis{}
390+ result := &mcp.ToolResult{
391+ Content: []mcp.ContentBlock{{Type: "text", Text: "success result"}},
392+ IsError: false,
393+ }
394+ got := m.formatToolResult("call_1", "test_tool", result, nil)
395+ if !strings.Contains(got, "call_1:success result") {
396+ t.Fatalf("expected success format, got: %s", got)
397+ }
398+ if strings.Contains(got, "Error") {
399+ t.Fatal("should not contain Error prefix for successful results")
400+ }
401+}
internal/core/mysis_tools_test.go+2−1
@@ -4,6 +4,7 @@ import (
44 "context"
55 "encoding/json"
66 "errors"
7+ "strings"
78 "testing"
89 "time"
910
@@ -180,7 +181,7 @@ func TestMysisToolError(t *testing.T) {
180181 for time.Now().Before(deadline) {
181182 memories, _ := s.GetMemories(stored.ID)
182183 for _, m := range memories {
183- if m.Role == store.MemoryRoleTool && m.Content == "call_err:Error: tool failed" {
184+ if m.Role == store.MemoryRoleTool && strings.Contains(m.Content, "call_err:Error calling error_tool: tool failed") {
184185 foundError = true
185186 break
186187 }