xonecas.io
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