60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / current / KNOWN_ISSUES.md
8.9 KB
1# Known Issues & Technical Debt 2 3Active todo list of known issues, bugs, and planned improvements for Zoea Nova. 4 5## High Priority 6 7## Medium Priority 8 9## Low Priority 10 11### TUI / Rendering 12 13- [ ] **Exit splash screen** - Display branding, connection cleanup status, and animated loading bar during shutdown 14 - **Trigger:** User presses q/ESC/CTRL+C 15 - **Purpose:** Provide visual feedback during graceful shutdown 16 - **Needs:** Splash screen design with loading animation 17 18- [ ] **Inconsistent JSON rendering in tool messages** - Some tool results render as raw text with tool call ID prefix 19 - **Example:** `chatcmpl-tool-XXX:{"player": {...}}` instead of tree view 20 - **Location:** `internal/tui/focus.go` - `renderLogEntry()` 21 - **Action:** Audit JSON detection logic for consistency 22 23### Testing / Coverage 24 25- [ ] **TUI integration tests skipped (config setup)** - Two tests skipped due to missing provider config 26 - **Tests:** `TestIntegration_NewMysisInput`, `TestIntegration_CreateAndStartMysis` 27 - **Root Cause:** Tests need temp config file after DefaultConfig() removal (commit 068a5a6) 28 - **Action:** Update tests to use setupTUITest() pattern from tui_test.go:32-56 29 30### Provider Reliability 31 32- [ ] **OpenCode provider crashes with undefined input_tokens** - Provider returns 500 errors when processing usage statistics 33 - **Error:** `Cannot read properties of undefined (reading 'input_tokens')` 34 - **Impact:** Causes myses to enter `errored` state and stop operating 35 - **Observed:** 2026-02-09 04:14:57 UTC - `nano` mysis (zen-nano provider) crashed after multiple successful turns 36 - **Pattern:** Error occurs during response processing, likely in usage statistics handling 37 - **Root cause:** OpenCode provider response format may not include expected `usage.input_tokens` field, or field is null/undefined 38 - **Location:** Provider response parsing in `internal/provider/opencode.go` or OpenCode SDK 39 - **Workaround:** None currently - requires provider restart to recover 40 - **Action needed:** 41 - Add defensive null checks for usage statistics fields 42 - Make usage statistics optional/non-fatal 43 - Log raw response when usage parsing fails for debugging 44 - **Related:** May be connected to zen-nano vs zen-pickle provider differences 45 46- [ ] **OpenCode Zen endpoint workaround for gpt-5-nano** - Using `/chat/completions` instead of documented `/responses` endpoint 47 - **Issue:** Official docs specify `gpt-5-nano` uses `/v1/responses` endpoint, but this returns HTTP 500 errors 48 - **Error:** `request failed after 3 retries: chat completion status 500` with server error mentioning `input_tokens` (Anthropic field) 49 - **Root cause:** `/responses` endpoint appears to expect non-OpenAI request format; our code uses OpenAI SDK with Chat Completions format 50 - **Workaround:** Hardcoded `gpt-5-nano` to use `/chat/completions` endpoint (works but contradicts official docs) 51 - **Location:** `internal/provider/opencode.go` line 53 52 - **Action needed:** Contact OpenCode support to clarify `/responses` endpoint format or confirm `/chat/completions` is acceptable 53 - **Reference:** https://opencode.ai/docs/zen/#models 54 55- [ ] **Investigate Ollama timeout errors** - Occasional "context deadline exceeded" errors when calling Ollama chat completions 56 - **Error:** `Post "http://localhost:11434/v1/chat/completions": context deadline exceeded` 57 - **Needs:** Root cause analysis (model size, request timeout configuration) 58 - **Recent evidence (2026-02-05):** Ollama logs show prompt truncation (`limit=32768`, `prompt=41611`) followed by bursts of `400` responses on `/v1/chat/completions` and one `500` response. No corresponding errors in `~/.zoea-nova/zoea.log`. 59 60### Documentation & Tooling 61 62- [ ] **Add plan enforcement command** - OpenCode slash command to require plan/todo creation before implementation 63 - **Purpose:** Enforce workflow discipline for complex changes 64 65- [ ] **Add documentation audit command** - OpenCode slash command to audit AGENTS.md and README.md against codebase using @explore 66 - **Purpose:** Keep documentation in sync with code changes 67 68### Operations 69 70- [ ] **Validate game server API changes** - Monitor and validate MCP and SpaceMolt game server updates for breaking changes 71 - **Reference:** `documentation/current/KNOWN_SERVER_ISSUES.md` 72 - **Process:** Periodic checks against upstream API 73 74--- 75 76## Recently Resolved 77 78- [x] **TestStateTransition_Running_To_Idle hangs** (2026-02-08) - Fixed goroutine leak in idle transition. Root cause: `setIdle()` wasn't canceling the context, causing the run loop goroutine to continue running. Added context cancellation to `setIdle()` method (lines 1092-1096 in `mysis.go`). The run loop now exits cleanly when transitioning to idle state. Test passes consistently in ~0.003-0.005s. Fixed in commit `d7a675a`. 79 80- [x] **Network indicator shows idle despite active Myses** (2026-02-07) - Fixed missing `EventNetworkIdle` after successful MCP tool execution and added counter tracking for network operations. Root cause: `EventNetworkMCP` was published for each tool call but `EventNetworkIdle` was only published on errors, causing counter to grow unbounded. Added `activeNetworkOps` counter in TUI that increments on LLM/MCP events and decrements on idle events. Indicator now correctly shows activity for both user-initiated and autonomous operations. See `documentation/architecture/NETWORK_EVENT_GUARANTEES.md` for event contract. Coverage improved from 85.0% to 85.3%. 81 82- [x] **Config validation and type safety** (2026-02-05) - Added comprehensive config validation with aggregated errors for provider/swarm settings. Replaced Event.Data interface{} with typed fields for type safety. Standardized Mysis receiver names. Coverage improved from 61% to 71.4%. 83 84- [x] **Testing coverage expansion** (2026-02-05) - Added config validation tests (11 subtests), provider error handling tests, HTTP mocking for tool calls, MCP proxy tests, and concurrent write benchmark (p50: 0.3ms, p99: 1.9ms). 85 86- [x] **Memory growth analysis** (2026-02-05) - Documented memory growth rate (279 memories/hour, 0.96 MB/hour DB growth). DB size is not a concern for v1. See `documentation/reports/MEMORY_GROWTH_REPORT.md`. 87 88- [x] **Ollama reliability investigation** (2026-02-05) - Analyzed 24h of Ollama logs. Found 65 HTTP 500s, 19 HTTP 400s, 3 prompt truncations, 23 client disconnects. Evidence documented in KNOWN_ISSUES.md for future investigation. 89 90- [x] **State-aware ContinuePrompt** (2026-02-05) - Implemented activity state tracking (idle, traveling, mining, in_combat, cooldown) to suppress nudges during known wait states. Parses arrival_tick and cooldown_ticks from tool results. 91 92- [x] **Prompt reinforcement and time awareness** (2026-02-05) - Reinforced critical rules in ContinuePrompt with drift detection. Removed real-time awareness, replaced with game tick time instructions. Added captain's log guidance with limits and examples. 93 94- [x] **TUI Enhancements** (2026-02-05) - Implemented display reasoning in focus view, account status in dashboard and focus header, JSON tree rendering with verbose toggle, and visual scrollbar indicator. Improves readability and navigation UX. 95 96- [x] **Track broadcast sender and suppress self-response** (2026-02-05) - Added sender_id to memories (schema v8), excluded sender from broadcast recipients, and updated focus view labels to distinguish swarm broadcasts from self broadcasts. 97 98- [x] **Tool payload bloat removal** (2026-02-04) - Removed `provider` and `state` fields from MysisInfo struct and `zoea_list_myses` tool payload. Added `GetStateCounts()` method to Commander for `zoea_swarm_status`. Saves ~22 tokens per mysis, ~352 tokens for full swarm (16 myses). **Note:** Both `zoea_list_myses` and `zoea_swarm_status` tools were later removed entirely. 99 100- [x] **Context snapshot compaction** (2026-02-04) - Implemented snapshot compaction in `getContextMemories()` to keep only most recent result for each snapshot tool (get_ship, get_system, get_poi, get_nearby, get_cargo). Added search tool reminders to SystemPrompt and ContinuePrompt. See `documentation/architecture/CONTEXT_COMPRESSION.md` for details. 101 102- [x] **Database reset with account backup** (2026-02-05) - Added `make db-reset-accounts` target to safely wipe database while preserving account credentials via export/import cycle. 103 104- [x] **Goroutine cleanup on exit** (2026-02-06) - Fixed terminal hangs and errored state on quit. Implemented complete goroutine cleanup with timeouts, WaitGroup tracking, and graceful shutdown sequence. See `documentation/plans/2026-02-06-goroutine-cleanup-fixes.md`. 105 106- [x] **OpenCode Zen 500 errors** (2026-02-07) - Fixed system-only message crashes, added Stream parameter, improved message merging, added validation. See `documentation/reports/OPENCODE_ZEN_FIX_2026-02-07.md`. 107 108- [x] **Session ID claim→login loops** (2026-02-07) - Fixed infinite loops caused by session_required errors. Added prompt reinforcement and error message interception. See `documentation/reports/SESSION_ID_LOOP_FIX_IMPLEMENTATION_2026-02-07.md`.