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