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:

# Check if DO is deployed
cd bandit-runner-app
wrangler deployments list

Fix:

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:

# 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:

# 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:

# 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

// 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

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!