ChatDev/docs/user_guide/en/ws_frontend_logic.md

WebSocket Connection Lifecycle Analysis

Scenario: Workflow Completed/Cancelled → File Change/Relaunch → Launch

Initial State (Workflow Completed/Cancelled)

Variables:

• status.value = 'Completed' or 'Cancelled'
• isWorkflowRunning.value = false
• shouldGlow.value = true (set by watch on status)
• ws = existing WebSocket connection (still open)
• sessionId = current session ID
• isConnectionReady.value = true

---

Scenario 1: Another File is Chosen

Step 1: File Selection Triggers Watch

Function: watch(selectedFile, (newFile) => {...}) (line 879)

Process:

1. taskPrompt.value = '' - clears input
2. fileSearchQuery.value = newFile || '' - updates search query
3. isFileSearchDirty.value = false - resets search state

Step 2: WebSocket Disconnection

Function: resetConnectionState({ closeSocket: true }) (line 443) Called at: line 891

What happens:

• ✅ WebSocket DISCONNECTED - ws.close() is called (line 446)
• ws = null (line 452)
• sessionId = null (line 453)
• isConnectionReady.value = false (line 454)
• shouldGlow.value = false (line 455)
• isWorkflowRunning.value = false (line 456)
• activeNodes.value = [] (line 457)
• Clears attachment timeouts and uploaded attachments

Status: status.value = 'Connecting...' (line 892)

Step 3: Load YAML

Function: handleYAMLSelection(newFile) (line 706) Called at: line 893

What happens:

• Clears chatMessages.value = []
• Fetches YAML file content
• Parses YAML and stores in workflowYaml.value
• Displays initial_instruction as notification
• Loads VueFlow graph

Step 4: WebSocket Reconnection

Function: establishWebSocketConnection() (line 807) Called at: line 894

What happens:

1. Double Reset: Calls resetConnectionState() again (line 809) - ensures clean state
2. New WebSocket Created:
   • const socket = new WebSocket('ws://localhost:8000/ws') (line 816)
   • ws = socket (line 817)
3. Connection Events:
   • socket.onopen (line 819): Logs "WebSocket connected"
   • socket.onmessage (line 825):
     • Receives connection message with session_id
     • Sets sessionId (line 832)
     • Sets isConnectionReady.value = true (line 842)
     • Sets shouldGlow.value = true (line 843)
     • Sets status.value = 'Waiting for launch...' (line 844)
   • socket.onerror (line 854): Handles connection errors
   • socket.onclose (line 864): Handles disconnection

Status: status.value = 'Waiting for launch...' (after connection message received)

---

Scenario 2: Relaunch Button Clicked

Step 1: Button Click Handler

Function: handleButtonClick() (line 740) Triggered: When Launch button is clicked and status is 'Completed'/'Cancelled'

Condition Check:

else if (status.value === 'Completed' || status.value === 'Cancelled')

Step 2: WebSocket Disconnection

Function: resetConnectionState() (line 443) Called at: line 754

What happens:

• ✅ WebSocket DISCONNECTED - ws.close() is called
• All state variables reset (same as Scenario 1, Step 2)

Status: status.value = 'Connecting...' (line 755)

Step 3: Load YAML

Function: handleYAMLSelection(selectedFile.value) (line 706) Called at: line 756

What happens: Same as Scenario 1, Step 3

Step 4: WebSocket Reconnection

Function: establishWebSocketConnection() (line 807) Called at: line 757

What happens: Same as Scenario 1, Step 4

Status: status.value = 'Waiting for launch...' (after connection message received)

---

Step 5: Launch Button Clicked (After Reconnection)

Launch Workflow

Function: launchWorkflow() (line 1124) Triggered: When Launch button is clicked and status is 'Waiting for launch...'

Prerequisites Check:

• selectedFile.value must exist
• taskPrompt.value.trim() or attachmentIds.length > 0 must exist
• ws, isConnectionReady.value, and sessionId must be valid

What happens:

1. Sets shouldGlow.value = false (line 1150)
2. Sets status.value = 'Launching...' (line 1151)
3. Sends POST request to /api/workflow/execute with:
   • yaml_file: selected file name
   • task_prompt: user input
   • session_id: current session ID
   • attachments: uploaded attachment IDs
4. On success:
   • Clears uploaded attachments
   • Adds user dialogue to chat
   • Sets status.value = 'Running...' (line 1185)
   • Sets isWorkflowRunning.value = true (line 1186)

Status: status.value = 'Running...'

---

Key Variables and Their Roles

WebSocket State Variables

Variable	Type	Purpose	Changes When
ws	WebSocket | null	Current WebSocket connection	Set to null on disconnect, new socket on connect
sessionId	string | null	Current session identifier	Set from connection message, cleared on reset
isConnectionReady	ref<boolean>	Whether connection is ready for launch	true after connection message, false on reset

Status Variables

Variable	Type	Purpose	Values
status	ref<string>	Current workflow status	'Completed', 'Cancelled', 'Connecting...', 'Waiting for launch...', 'Launching...', 'Running...'
isWorkflowRunning	ref<boolean>	Whether workflow is actively running	true during execution, false otherwise
shouldGlow	ref<boolean>	UI glow effect state	true when ready for input, false during execution

Workflow State Variables

Variable	Type	Purpose
selectedFile	ref<string>	Currently selected YAML file
workflowYaml	ref<object>	Parsed YAML content
activeNodes	ref<string[]>	List of currently active node IDs
chatMessages	ref<array>	All chat messages and notifications

---

WebSocket Connection Timeline

When Disconnected:

1. File Change: watch(selectedFile) → resetConnectionState() → ws.close()
2. Relaunch: handleButtonClick() → resetConnectionState() → ws.close()
3. Error/Close Events: socket.onerror or socket.onclose → resetConnectionState({ closeSocket: false })

When Reconnected:

1. File Change: watch(selectedFile) → establishWebSocketConnection() → new WebSocket()
2. Relaunch: handleButtonClick() → establishWebSocketConnection() → new WebSocket()

Connection States:

[Completed/Cancelled] 
    ↓ (File Change or Relaunch)
[Disconnected] → resetConnectionState() closes ws
    ↓
[Connecting...] → establishWebSocketConnection() creates new ws
    ↓
[WebSocket.onopen] → socket opened
    ↓
[WebSocket.onmessage: 'connection'] → sessionId received
    ↓
[Waiting for launch...] → isConnectionReady = true
    ↓ (Launch clicked)
[Launching...] → POST /api/workflow/execute
    ↓
[Running...] → isWorkflowRunning = true

---

Important Notes

1. Double Reset Issue: establishWebSocketConnection() calls resetConnectionState() at the start (line 809), which means when called after resetConnectionState() in the caller, it's resetting twice. This is safe but redundant.

2. Stale Socket Protection: All WebSocket event handlers check if (ws !== socket) return to ignore events from old sockets that were replaced.

3. Status Transitions: The status goes through these states:

   • Completed/Cancelled → Connecting... → Waiting for launch... → Launching... → Running...

4. Connection Ready Check: launchWorkflow() verifies ws, isConnectionReady.value, and sessionId before allowing launch.

5. Automatic Reconnection: Both file change and relaunch automatically establish a new WebSocket connection - no manual reconnection needed.