60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / MESSAGE_FORMAT_GUARANTEES.md
11.5 KB
1# Message Format Guarantees 2 3## Purpose 4 5This document defines how Zoea Nova ensures every LLM request has proper OpenAI-compatible message format: `[system][user][assistant?][tool?]...` 6 7The message format guarantee is the **single source of truth** for when and how synthetic messages are added to conversation history. 8 9--- 10 11## Core Principle 12 13**One place, one time:** Synthetic messages are added **only** in `getContextMemories()`, nowhere else. 14 15No other code adds or removes messages from context: 16- Provider layer converts types but does not modify message lists 17- Mysis loop sends context as-is from `getContextMemories()` 18- Commander broadcasts and direct messages go to database, never injected mid-flight 19 20--- 21 22## The Encouragement System 23 24When no real user message exists in the database, `getContextMemories()` adds a synthetic encouragement message to satisfy OpenAI format requirements. 25 26### Encouragement Counter 27 28**Purpose:** Track consecutive synthetic messages to detect idle myses. 29 30**Behavior:** 31- Counter increments when synthetic message is added 32- Counter resets to 0 when real user message (broadcast/direct) exists 33- After 3 consecutive synthetic messages, mysis transitions to idle 34 35### Truth Table 36 37| State | User Msg in DB? | Action | Counter | Next State | 38|-------|-----------------|--------|---------|------------| 39| Running | Yes (broadcast) | Use real message | Reset to 0 | Running | 40| Running | Yes (direct) | Use real message | Reset to 0 | Running | 41| Running | No | Add synthetic | +1 (now 1) | Running | 42| Running | No | Add synthetic | +1 (now 2) | Running | 43| Running | No | Add synthetic | +1 (now 3) | **Idle** | 44| Idle | Yes (broadcast) | Auto-start | Reset to 0 | Running | 45| Idle | Yes (direct) | Start via API | Reset to 0 | Running | 46| Idle | No | — | — | Idle | 47 48--- 49 50## Message Sources 51 52### Real User Messages (Reset Counter) 53 541. **Commander Broadcast** - User types `b` in TUI and sends message to all myses 552. **Direct Message** - User types `m` in TUI and targets specific mysis 56 57All real user messages: 58- Are stored in database with `role=user` and `source=broadcast|direct` 59- Reset encouragement counter to 0 60- Start idle myses automatically (broadcasts) or via API call (direct) 61 62**Note:** Myses cannot broadcast to each other. Only the Commander (via TUI) can send broadcast messages to the swarm. 63 64### Synthetic Messages (Increment Counter) 65 66**Source:** `getContextMemories()` line 1461-1478 67 68**When added:** No real user message found in `findLastUserPromptIndex()` 69 70**Content:** `"Continue your mission. Check notifications and coordinate with the swarm."` 71 72**Format:** 73```go 74&store.Memory{ 75 Role: store.MemoryRoleUser, 76 Source: store.MemorySourceSystem, 77 Content: nudgeContent, 78 SenderID: "", 79 CreatedAt: time.Now(), 80} 81``` 82 83**Not persisted to database** - exists only in context slice sent to LLM. 84 85--- 86 87## Mysis Lifecycle 88 89### Creation 90 91``` 92Commander creates mysis via TUI 93 ↓ 94Mysis starts in idle state 95 ↓ 96No messages in database 97 ↓ 98Waits for user message to start 99``` 100 101### Running (No Broadcasts) 102 103``` 104Mysis.Start() called 105 ↓ 106Loop iteration 1: 107 getContextMemories() → No user message → Add synthetic → Counter = 1 108 ↓ 109LLM responds, tools execute 110 ↓ 111Loop iteration 2: 112 getContextMemories() → Still no user message → Add synthetic → Counter = 2 113 ↓ 114LLM responds, tools execute 115 ↓ 116Loop iteration 3: 117 getContextMemories() → Still no user message → Add synthetic → Counter = 3 118 ↓ 119Counter >= 3 → Transition to idle 120 ↓ 121Waits for real user message 122``` 123 124### Running (With Broadcasts) 125 126``` 127Commander sends broadcast "Explore the universe!" 128 ↓ 129Stored in database with role=user, source=broadcast 130 ↓ 131Mysis.Start() called (or auto-started if idle) 132 ↓ 133Loop iteration 1: 134 getContextMemories() → Finds broadcast → Use it → Counter = 0 135 ↓ 136LLM responds: "I will navigate to node_alpha..." 137 ↓ 138Loop iteration 2: 139 getContextMemories() → Broadcast still most recent → Use it → Counter = 0 140 ↓ 141LLM responds: "[TOOL_CALLS]navigate:..." 142 ↓ 143Loop continues until: 144 - New broadcast arrives (resets counter) 145 - Direct message arrives (resets counter) 146 - 3 consecutive iterations with no user message (goes idle) 147``` 148 149### Idle Recovery 150 151``` 152Mysis idle (counter = 3, no user messages) 153 ↓ 154Commander sends broadcast "Mine iron ore" 155 ↓ 156Broadcast stored in database 157 ↓ 158Mysis auto-starts (QueueBroadcast triggers Start()) 159 ↓ 160Loop iteration 1: 161 getContextMemories() → Finds new broadcast → Counter = 0 162 ↓ 163Mysis active again 164``` 165 166--- 167 168## Code Locations 169 170### Primary Implementation 171 172**`internal/core/mysis.go:getContextMemories()`** (lines 1169-1268) 173- Checks for real user messages via `findLastUserPromptIndex()` 174- **Sliding Window Protection:** If no user message found in recent 20 messages, checks for broadcast in full DB 175- Adds synthetic message only if no broadcast exists anywhere 176- **This is the only place synthetic messages are added** 177 178**`internal/store/memories.go:GetMostRecentBroadcast()`** (lines 233-286) 179- Retrieves most recent broadcast for a mysis from full database 180- **Global fallback:** If no broadcast for this mysis, returns most recent broadcast from any mysis 181- Used to prevent idle state when broadcasts exist outside sliding window 182- Ensures new myses inherit current swarm mission 183 184### Counter Management 185 186**Increment:** In `getContextMemories()` when synthetic message added (no broadcast exists) 187```go 188// After adding synthetic message 189a.mu.Lock() 190a.encouragementCount++ 191count := a.encouragementCount 192a.mu.Unlock() 193 194if count >= 3 { 195 // Transition to idle 196} 197``` 198 199**Reset:** When real user message arrives OR when broadcast found in DB 200```go 201// In QueueBroadcast (line 719) and SendMessageFrom (line 392) 202a.mu.Lock() 203a.encouragementCount = 0 204a.mu.Unlock() 205 206// Also in getContextMemories when broadcast found outside sliding window (line 1211) 207a.mu.Lock() 208a.encouragementCount = 0 209a.mu.Unlock() 210``` 211 212### Obsolete Code (To Be Removed) 213 214**`internal/provider/openai_common.go`:** 215- Lines 166-173: "Begin." fallback - **Remove** 216- Lines 175-184: "Continue." fallback - **Remove** 217 218**`internal/core/mysis.go`:** 219- Lines 1676-1727: Ticker-based nudge system - **Remove** 220- Field `nudgeCh chan struct{}` - **Remove** 221- Method `buildContinuePrompt()` with escalation - **Remove** 222 223--- 224 225## OpenAI Format Requirements 226 227The OpenAI Chat Completions API requires: 2281. **System messages first** - Handled by provider message conversion 2292. **At least one user message** - Guaranteed by encouragement system 2303. **Alternating user/assistant** - Natural conversation flow 2314. **Tool results follow tool calls** - Handled by tool loop logic 232 233The encouragement system ensures requirement #2. The other requirements are satisfied by normal conversation flow and provider message conversion. 234 235--- 236 237## Sliding Window Protection 238 239### The Problem 240 241Context is limited to the most recent 20 messages (`MaxContextMessages = 20`). When a mysis processes a broadcast and generates 20+ messages (assistant responses, tool calls, tool results), the original broadcast is pushed out of the sliding window. 242 243**Example:** 2441. Broadcast stored: "Explore the universe!" (message #1) 2452. Mysis processes it, generates 24 messages (8 iterations × 3 messages each) 2463. Total: 25 messages in database 2474. `GetRecentMemories(20)` returns only messages #6-25 2485. Broadcast (message #1) is excluded 2496. `findLastUserPromptIndex` returns -1 (no user message found) 2507. Synthetic encouragement added, counter increments 2518. After 3 iterations: mysis incorrectly goes idle despite having mission directive 252 253### The Solution 254 255When `findLastUserPromptIndex` returns -1 (no user message in sliding window), `getContextMemories` performs a secondary check: 256 2571. Query database for most recent broadcast: `GetMostRecentBroadcast(mysisID)` 2582. If broadcast exists (even outside window), include it in context 2593. Reset encouragement counter to 0 2604. Mysis continues running with mission directive 261 262**Code Location:** `internal/core/mysis.go:1203-1225` 263 264**Global Fallback:** `GetMostRecentBroadcast` has two-tier lookup: 2651. First, search for broadcasts sent to this specific mysis 2662. If none found, search for most recent Commander broadcast in entire system (global swarm mission) 2673. This ensures new myses created after a Commander broadcast inherit the current mission 268 269**Benefits:** 270- Ensures autonomous operation: myses stay running as long as broadcasts exist 271- New myses inherit swarm mission: no idle state for late joiners 272- Minimal token cost: adds 1 broadcast message to context 273- Maintains truth table guarantees: broadcasts always keep myses running 274 275**Test Coverage:** 276- `TestBroadcastSlidingWindowBug` (internal/core/mysis_test.go:2397) 277- `TestNewMysisInheritsGlobalBroadcast` (internal/core/mysis_test.go:2507) 278 279--- 280 281## Design Rationale 282 283### Why One Place? 284 285**Clarity:** Anyone debugging message format issues knows to check `getContextMemories()` only. 286 287**Correctness:** No risk of multiple code paths adding conflicting synthetic messages. 288 289**Testability:** Mock database content, call `getContextMemories()`, verify output. 290 291### Why Not Provider Layer? 292 293The provider layer converts message types (`store.Memory` → `openai.ChatCompletionMessage`). It should not modify message lists. 294 295Adding synthetic messages in the provider layer would: 296- Hide the logic far from where context is built 297- Make it harder to track encouragement counter 298- Duplicate logic across multiple providers (OpenCode, Ollama, etc.) 299 300### Why Not Ticker? 301 302A ticker nudges every 30 seconds regardless of database state. This creates synthetic messages even when real user messages exist. 303 304The ticker-based approach: 305- Adds unnecessary messages to conversation history 306- Increments counter based on time, not actual message presence 307- Conflicts with database-driven context building 308 309--- 310 311## Migration Path 312 313**Current state:** Ticker-based nudges + provider-layer fallbacks + context-layer synthetic messages 314 315**Target state:** Context-layer synthetic messages only 316 317**Steps:** 3181. Document this architecture (this file) 3192. Remove ticker goroutine and `nudgeCh` from `mysis.go` 3203. Remove "Begin." and "Continue." fallbacks from `openai_common.go` 3214. Rename `nudgeFailCount` to `encouragementCount` for clarity 3225. Move counter increment/reset to `getContextMemories()` and message handlers 3236. Update tests to verify new behavior 324 325--- 326 327## Testing Strategy 328 329### Unit Tests 330 331**Test:** `getContextMemories()` with no user messages 332- **Verify:** Synthetic message added 333- **Verify:** Counter increments 334 335**Test:** `getContextMemories()` with broadcast in DB 336- **Verify:** Real message used 337- **Verify:** Counter resets to 0 338 339**Test:** 3 consecutive calls with no user messages 340- **Verify:** Counter reaches 3 341- **Verify:** Mysis transitions to idle 342 343### Integration Tests 344 345**Test:** Create mysis, start without broadcasts 346- **Verify:** Runs 3 iterations 347- **Verify:** Goes idle 348 349**Test:** Create mysis, send broadcast, start 350- **Verify:** Uses broadcast message 351- **Verify:** Counter stays at 0 352- **Verify:** Continues running 353 354**Test:** Idle mysis receives broadcast 355- **Verify:** Auto-starts 356- **Verify:** Counter resets 357 358--- 359 360## Summary 361 362- **One source of truth:** `getContextMemories()` adds synthetic messages 363- **Counter tracks encouragements:** 3 consecutive = idle 364- **Real messages reset counter:** Broadcasts and directs keep myses running 365- **No ticker, no provider fallbacks:** Obsolete patterns removed 366- **Database-driven:** Context built from persisted messages only 367 368This design ensures every LLM request has proper OpenAI format while keeping myses idle when no real user messages exist. 369 370--- 371 372Last updated: 2026-02-07