bandit-runner/docs/development_documentation/DEBUGGING-GUIDE.md

# Debugging Guide - WebSocket & Event Flow

## Quick Debugging Steps

### 1. Check WebSocket Connection

1. Open browser (Chrome/Firefox)
2. Go to https://bandit-runner-app.nicholaivogelfilms.workers.dev/
3. Open DevTools: F12 or Right-click → Inspect
4. Go to **Console** tab
5. Click **START** button
6. Look for these messages:

**Expected Console Output**:
```
✅ WebSocket connected to: wss://bandit-runner-app.nicholaivogelfilms.workers.dev/api/agent/run-xxx/ws
📨 WebSocket message received: {"type":"agent_message","data":{...}}
📦 Parsed event: agent_message {content: "Starting run..."}
🎯 handleAgentEvent called: agent_message {content: "Starting run..."}
💬 Adding chat message: Starting run...
```

### 2. Check Network Tab

1. Open DevTools → **Network** tab
2. Filter by **WS** (WebSocket)
3. Click START
4. Look for `/api/agent/run-xxx/ws`
5. Check **Status**: Should be `101 Switching Protocols`

**If you see**:
- ✅ `101` - WebSocket upgraded successfully
- ❌ `404` - Route not found (check deployment)
- ❌ `500` - Server error (check Durable Object)
- ❌ `426` - Upgrade required (WebSocket header issue)

### 3. Check WebSocket Messages

1. Click on the WebSocket connection in Network tab
2. Go to **Messages** subtab
3. You should see:

```
↑ {"type":"ping"}  (every 30s)
↓ {"type":"pong"}  (response)
↓ {"type":"agent_message","data":{"content":"Starting run..."}}
↓ {"type":"thinking","data":{"content":"I need to read..."}}
↓ {"type":"terminal_output","data":{"content":"$ cat readme"}}
```

## Common Issues & Fixes

### Issue 1: No WebSocket Connection

**Symptom**: Console shows nothing when clicking START

**Check**:
```bash
# Check if DO is deployed
cd bandit-runner-app
wrangler deployments list
```

**Fix**:
```bash
cd bandit-runner-app
pnpm run deploy
```

### Issue 2: WebSocket Connects but No Messages

**Symptom**: 
```
✅ WebSocket connected to: wss://...
(no other messages)
```

**This means**: DO is working, but SSH proxy isn't sending events

**Check SSH Proxy**:
```bash
# Check SSH proxy logs
flyctl logs -a bandit-ssh-proxy
```

**Look for**:
- ✅ `POST /agent/run` request received
- ✅ Agent started
- ✅ SSH connection attempt
- ❌ Errors connecting to Bandit server
- ❌ Missing OPENROUTER_API_KEY

**Fix**:
```bash
# Ensure SSH proxy is running
fly status -a bandit-ssh-proxy

# Check environment variables
fly secrets list -a bandit-ssh-proxy
```

### Issue 3: Messages Received but Terminal/Chat Empty

**Symptom**:
```
✅ WebSocket connected
📨 WebSocket message received: {...}
📦 Parsed event: agent_message {content: "..."}
🎯 handleAgentEvent called: agent_message {content: "..."}
💬 Adding chat message: ...
(but chat panel is still empty)
```

**This means**: Events are being processed but React state isn't updating UI

**Check**:
1. Look at React DevTools
2. Find `TerminalChatInterface` component
3. Check `wsChatMessages` state
4. Check `wsTerminalLines` state

**If state is updating but UI isn't**: React rendering issue

**Fix**: Check if `wsTerminalLines` and `wsChatMessages` are being mapped correctly in JSX

### Issue 4: SSH Connection Fails

**Symptom** in SSH proxy logs:
```
SSH connection failed: Connection refused
or
SSH connection failed: Authentication failed
```

**Fix**:
```bash
# Test SSH connection manually
ssh bandit0@bandit.labs.overthewire.org -p 2220
# Password: bandit0
```

If manual SSH works but agent fails:
- Check password in agent state
- Check SSH proxy can reach bandit.labs.overthewire.org
- Check Fly.io network policies

## Testing Checklist

Use this to verify each part of the system:

### Frontend
- [ ] Page loads
- [ ] Can select model
- [ ] Can click START
- [ ] `runId` is generated
- [ ] `/api/agent/xxx/start` request succeeds

### WebSocket
- [ ] WebSocket connection established (check Network tab)
- [ ] Status shows `101 Switching Protocols`
- [ ] Ping/pong messages every 30s
- [ ] Can see messages in Network → WS → Messages

### Durable Object
- [ ] `/start` endpoint returns success
- [ ] WebSocket upgrade works
- [ ] Events are broadcast to clients
- [ ] Check Wrangler logs: `wrangler tail`

### SSH Proxy
- [ ] `/agent/run` endpoint receives request
- [ ] Agent initializes
- [ ] SSH connection established
- [ ] Commands execute
- [ ] Events stream back as JSONL

### Event Flow
- [ ] WebSocket receives events
- [ ] Events are parsed
- [ ] `handleAgentEvent` is called
- [ ] Terminal state updates
- [ ] Chat state updates
- [ ] UI re-renders with new content

## Manual Testing

### Test WebSocket Directly

```javascript
// Run in browser console
const ws = new WebSocket('wss://bandit-runner-app.nicholaivogelfilms.workers.dev/api/agent/test-123/ws')

ws.onopen = () => console.log('Connected')
ws.onmessage = (e) => console.log('Message:', e.data)
ws.onerror = (e) => console.error('Error:', e)

// Should see: Connected
// Then try starting a run and watch for messages
```

### Test SSH Proxy Directly

```bash
curl -X POST https://bandit-ssh-proxy.fly.dev/agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "runId": "test-123",
    "modelName": "openai/gpt-4o-mini",
    "apiKey": "YOUR_OPENROUTER_API_KEY",
    "startLevel": 0,
    "endLevel": 0
  }'

# Should see JSONL events streaming:
{"type":"agent_message","data":{"content":"Starting..."}}
{"type":"thinking","data":{"content":"I need to..."}}
...
```

## Expected Event Sequence

When everything works, you should see this exact sequence:

1. **User clicks START**
2. Console: `✅ WebSocket connected to: wss://...`
3. Console: `📨 WebSocket message received: {"type":"agent_message",...}`
4. Console: `🎯 handleAgentEvent called: agent_message`
5. Console: `💬 Adding chat message: Starting run...`
6. **Chat panel updates**: "Starting run - Level 0 to 5 using..."
7. Console: `📨 WebSocket message received: {"type":"thinking",...}`
8. Console: `🧠 Adding thinking message: I need to read...`
9. **Chat panel updates**: "Planning: I need to read..."
10. Console: `📨 WebSocket message received: {"type":"terminal_output",...}`
11. Console: `💻 Adding terminal line: $ cat readme`
12. **Terminal panel updates**: "$ cat readme"
13. Console: `📨 WebSocket message received: {"type":"terminal_output",...}`
14. **Terminal panel updates**: [readme contents with ANSI colors]
15. Continue for password extraction, level complete, etc.

## Next Steps

Based on console output, you can determine:

1. **No WebSocket connection** → Check deployment
2. **WebSocket connects but no messages** → Check SSH proxy
3. **Messages received but not processed** → Check event handlers
4. **Events processed but UI not updating** → Check React state/rendering

Run through the checklist above and report back what you see in the console!