60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / NETWORK_EVENT_GUARANTEES.md
6.8 KB
1# Network Event Guarantees 2 3**Version:** 1.0 4**Created:** 2026-02-07 5**Status:** Design Document 6 7## Purpose 8 9Define the contract for network activity events (`EventNetworkLLM`, `EventNetworkMCP`, `EventNetworkIdle`) to ensure the TUI network indicator correctly reflects Mysis activity. 10 11## Problem Statement 12 13The network indicator shows idle despite running Myses actively making LLM/MCP calls. Investigation revealed: 14 151. **Symptom:** Network indicator shows "⬦ IDLE" when 4 Myses are running 162. **Expected:** Indicator should show "⬥ LLM" or "⬥ MCP" when any Mysis is making network calls 173. **Root Cause:** Mismatched event publishing - `EventNetworkMCP` published without corresponding `EventNetworkIdle` 18 19## Current Event Publishing (Broken) 20 21### LLM Call Flow 22``` 231. Publish EventNetworkLLM 242. Call provider.ChatWithTools() 253. If error: 26 - Publish EventNetworkIdle 27 - Return error 284. If success with tool calls: 29 - For each tool: 30 - Publish EventNetworkMCP 31 - Execute tool 32 - If tool error: Publish EventNetworkIdle, return 33 - If tool success: NO EVENT (BUG!) 34 - Continue loop (back to step 1) 355. If success without tool calls: 36 - Publish EventNetworkIdle 37 - Return success 38``` 39 40### The Bug 41 42**Line 607-653** (`internal/core/mysis.go`): 43```go 44for _, tc := range response.ToolCalls { 45 // Signal MCP activity 46 a.bus.Publish(Event{Type: EventNetworkMCP, ...}) // +1 to counter 47 48 result, execErr := a.executeToolCall(ctx, mcpProxy, tc) 49 50 // BUG: No EventNetworkIdle published here on success! 51 52 if execErr != nil && isToolTimeout(execErr) { 53 a.bus.Publish(Event{Type: EventNetworkIdle, ...}) // -1 on error 54 return 55 } 56 57 if execErr != nil && isToolRetryExhausted(execErr) { 58 a.bus.Publish(Event{Type: EventNetworkIdle, ...}) // -1 on error 59 return 60 } 61} 62// Loop continues without publishing idle event 63continue 64``` 65 66**Result:** Counter increments on every MCP call but never decrements on success, causing it to grow unbounded. 67 68## Truth Table: Network Events 69 70| Scenario | Event Published | Counter Change | When | 71|----------|----------------|----------------|------| 72| LLM call starts | `EventNetworkLLM` | +1 | Before `provider.ChatWithTools()` | 73| LLM call fails | `EventNetworkIdle` | -1 | After provider error | 74| LLM returns (no tools) | `EventNetworkIdle` | -1 | After storing response | 75| LLM returns (with tools) | *(none)* | 0 | Before tool execution loop | 76| MCP tool call starts | `EventNetworkMCP` | +1 | Before `executeToolCall()` | 77| MCP tool succeeds | **MISSING** | **0 (BUG!)** | After tool execution | 78| MCP tool timeout | `EventNetworkIdle` | -1 | After timeout error | 79| MCP tool retry exhausted | `EventNetworkIdle` | -1 | After retry error | 80| Max iterations exceeded | `EventNetworkIdle` | -1 | After loop exit | 81 82## Correct Event Publishing (Fixed) 83 84### Guarantee: Every Start Event Has Matching End Event 85 86**Rule 1:** Every `EventNetworkLLM` must have exactly one `EventNetworkIdle` 87**Rule 2:** Every `EventNetworkMCP` must have exactly one `EventNetworkIdle` 88**Rule 3:** Events must be published in the same goroutine (no race conditions) 89 90### Fixed LLM Call Flow 91``` 921. Publish EventNetworkLLM // +1 932. Call provider.ChatWithTools() 943. If error: 95 - Publish EventNetworkIdle // -1 (matches step 1) 96 - Return error 974. If success with tool calls: 98 - For each tool: 99 - Publish EventNetworkMCP // +1 100 - Execute tool 101 - Publish EventNetworkIdle // -1 (matches EventNetworkMCP) 102 - If tool error: return 103 - Continue loop (back to step 1) 1045. If success without tool calls: 105 - Publish EventNetworkIdle // -1 (matches step 1) 106 - Return success 107``` 108 109## Truth Table: Fixed Network Events 110 111| Scenario | Event Published | Counter Change | When | 112|----------|----------------|----------------|------| 113| LLM call starts | `EventNetworkLLM` | +1 | Before `provider.ChatWithTools()` | 114| LLM call fails | `EventNetworkIdle` | -1 | After provider error | 115| LLM returns (no tools) | `EventNetworkIdle` | -1 | After storing response | 116| LLM returns (with tools) | *(none)* | 0 | Before tool execution loop | 117| MCP tool call starts | `EventNetworkMCP` | +1 | Before `executeToolCall()` | 118| **MCP tool succeeds** | **`EventNetworkIdle`** | **-1** | **After tool execution** | 119| MCP tool timeout | `EventNetworkIdle` | -1 | After timeout error | 120| MCP tool retry exhausted | `EventNetworkIdle` | -1 | After retry error | 121| Max iterations exceeded | `EventNetworkIdle` | -1 | After loop exit | 122 123## Implementation Plan 124 125### Phase 1: Add Missing EventNetworkIdle 126 127**File:** `internal/core/mysis.go` 128**Location:** Line 622 (after `a.setActivity(ActivityStateIdle, time.Time{})`) 129 130**Change:** 131```go 132// Clear MCP activity state after call completes 133a.setActivity(ActivityStateIdle, time.Time{}) 134 135// Signal MCP activity complete (ADD THIS) 136a.bus.Publish(Event{Type: EventNetworkIdle, MysisID: a.id, Timestamp: time.Now()}) 137 138a.updateActivityFromToolResult(result, execErr) 139``` 140 141### Phase 2: Add Counter Tracking in TUI 142 143**File:** `internal/tui/app.go` 144 145**Add field:** 146```go 147activeNetworkOps int // Count of active network operations 148``` 149 150**Update event handlers:** 151```go 152case core.EventNetworkLLM: 153 m.activeNetworkOps++ 154 m.netIndicator.SetActivity(NetActivityLLM) 155 156case core.EventNetworkMCP: 157 m.activeNetworkOps++ 158 m.netIndicator.SetActivity(NetActivityMCP) 159 160case core.EventNetworkIdle: 161 m.activeNetworkOps-- 162 if m.activeNetworkOps < 0 { 163 m.activeNetworkOps = 0 // Safety 164 } 165 if m.activeNetworkOps == 0 { 166 m.netIndicator.SetActivity(NetActivityIdle) 167 } 168 m.refreshTick() 169``` 170 171### Phase 3: Add Test Coverage 172 173**Test 1:** Verify EventNetworkIdle published after successful MCP call 174**Test 2:** Verify counter tracks multiple concurrent operations 175**Test 3:** Verify indicator stays active when operations overlap 176**Test 4:** Verify counter doesn't go negative 177 178## Verification Checklist 179 180- [ ] Every `EventNetworkLLM` has matching `EventNetworkIdle` 181- [ ] Every `EventNetworkMCP` has matching `EventNetworkIdle` 182- [ ] Counter increments on LLM/MCP events 183- [ ] Counter decrements on idle events 184- [ ] Indicator shows idle only when counter == 0 185- [ ] No race conditions (all events in same goroutine) 186- [ ] Tests verify autonomous activity tracking 187- [ ] Manual testing with 4 running Myses shows active indicator 188 189## Code Locations 190 191- Event publishing: `internal/core/mysis.go:520-690` 192- Event handling: `internal/tui/app.go:782-801` 193- Network indicator: `internal/tui/netindicator.go` 194- Event types: `internal/core/types.go:43-45` 195 196## Migration Notes 197 198**Breaking Change:** No 199**Database Migration:** No 200**Config Change:** No 201**Backward Compatible:** Yes (only adds events, doesn't remove) 202 203--- 204 205**Version:** 1.0 206**Last Updated:** 2026-02-07