@@ -0,0 +1,206 @@
1+# Network Event Guarantees
2+
3+**Version:** 1.0
4+**Created:** 2026-02-07
5+**Status:** Design Document
6+
7+## Purpose
8+
9+Define the contract for network activity events (`EventNetworkLLM`, `EventNetworkMCP`, `EventNetworkIdle`) to ensure the TUI network indicator correctly reflects Mysis activity.
10+
11+## Problem Statement
12+
13+The network indicator shows idle despite running Myses actively making LLM/MCP calls. Investigation revealed:
14+
15+1. **Symptom:** Network indicator shows "⬦ IDLE" when 4 Myses are running
16+2. **Expected:** Indicator should show "⬥ LLM" or "⬥ MCP" when any Mysis is making network calls
17+3. **Root Cause:** Mismatched event publishing - `EventNetworkMCP` published without corresponding `EventNetworkIdle`
18+
19+## Current Event Publishing (Broken)
20+
21+### LLM Call Flow
22+```
23+1. Publish EventNetworkLLM
24+2. Call provider.ChatWithTools()
25+3. If error:
26+ - Publish EventNetworkIdle
27+ - Return error
28+4. 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)
35+5. 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
44+for _, 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
63+continue
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+```
92+1. Publish EventNetworkLLM // +1
93+2. Call provider.ChatWithTools()
94+3. If error:
95+ - Publish EventNetworkIdle // -1 (matches step 1)
96+ - Return error
97+4. 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)
104+5. 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
133+a.setActivity(ActivityStateIdle, time.Time{})
134+
135+// Signal MCP activity complete (ADD THIS)
136+a.bus.Publish(Event{Type: EventNetworkIdle, MysisID: a.id, Timestamp: time.Now()})
137+
138+a.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
147+activeNetworkOps int // Count of active network operations
148+```
149+
150+**Update event handlers:**
151+```go
152+case core.EventNetworkLLM:
153+ m.activeNetworkOps++
154+ m.netIndicator.SetActivity(NetActivityLLM)
155+
156+case core.EventNetworkMCP:
157+ m.activeNetworkOps++
158+ m.netIndicator.SetActivity(NetActivityMCP)
159+
160+case 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