gadget/docs/socket-protocol.md

Gadget Code Socket Protocol Reference

This document serves as a "Cheat Sheet" for AI agents and developers working on the Gadget Code real-time messaging system.

1. Components & Connections

Component	Role	Protocol	Auth Method
gadget-code:web	Hub / Router / Server	Socket.IO Server	N/A
gadget-code:ide	Frontend Control Surface	Socket.IO Client	JWT Token
gadget-drone	Worker / AWL Runner	Socket.IO Client	Drone Registration ID

---

2. Event Map Overview

Defined in packages/api/src/messages/socket.ts.

IDE -> Web (Client to Server)

• requestSessionLock: Request to exclusive-lock a drone for a project session.
• requestWorkspaceMode: Request a mode change (Idle, User, Agent).
• submitPrompt: Submit a user prompt for agent processing.

Drone -> Web (Client to Server)

• thinking: Stream reasoning/thought process text.
• response: Stream natural language response text.
• toolCall: Emit a specific tool execution event with result.
• workOrderComplete: Signal that a prompt processing turn is finished.
• requestCrashRecovery: Inbound from drone on restart if it finds a stalled work order.

Web -> Drone (Server to Client)

• processWorkOrder: Command to start processing a specific prompt/turn.
• crashRecoveryResponse: Command to discard or retry a stalled work order.

---

3. Core Sequences & Routing

3.1 Prompt Submission Flow

1. IDE emits submitPrompt(content).
2. Web (CodeSession.ts):
   • Creates a ChatTurn document (status: processing).
   • Finds the target DroneSession.
   • Emits processWorkOrder to the Drone.
3. Drone (gadget-drone.ts):
   • Writes a local .gadget/work-order.json cache (for crash recovery).
   • Calls AgentService.process().
   • Emits streaming events back to Web.

3.2 Result Streaming Flow

1. Drone emits thinking(text), response(text), or toolCall(id, name, args, result).
2. Web (DroneSession.ts):
   • Locates the associated CodeSession via SocketService.getCodeSessionByChatSessionId().
   • Updates the ChatTurn document in MongoDB incrementally.
   • Forwards the event to the IDE.
3. IDE: Updates the UI in real-time.

3.3 Session Termination

1. Drone emits workOrderComplete(turnId, success, message).
2. Web (DroneSession.ts):
   • Sets ChatTurn status to finished or error.
   • Forwards event to IDE.
   • Clears currentTurnId from the drone session.

---

4. Message Signatures (TS Reference)

IDE -> Web

type RequestSessionLockMessage = (
  registration: IDroneRegistration,
  project: IProject,
  chatSession: IChatSession,
  cb: (success: boolean, chatSessionId: string) => void
) => void;

type SubmitPromptMessage = (prompt: string) => void;

Web -> Drone

type ProcessWorkOrderMessage = (
  registration: IDroneRegistration,
  project: IProject,
  chatSession: IChatSession,
  turn: IChatTurn,
  cb: (success: boolean, message?: string) => void
) => void;

Drone -> Web (Streaming)

type ThinkingMessage = (content: string) => void;
type ResponseMessage = (content: string) => void;
type ToolCallMessage = (
  callId: string,
  name: string,
  params: string,   // JSON.stringify
  response: string  // JSON.stringify
) => void;

---

5. Session Implementation Guide (Web Server)

The web server (gadget-code:web) implements two wrapper classes in src/lib/:

CodeSession.ts

Manages the IDE socket.

• Logic: Maps User ID -> Socket ID.
• Routing: When an IDE sends a message, CodeSession finds the selected drone's DroneSession and forwards the command.

DroneSession.ts

Manages the Drone socket.

• Logic: Maps Drone Registration ID -> Socket ID.
• Routing: When a drone streams, DroneSession looks up the chatSessionId in the SocketService index to find the return path to the IDE.

---

6. Workspace Crash Recovery

1. Drone starts -> checks for .gadget/work-order.json.
2. If found, emits requestCrashRecovery({ workspaceId, turnId, chatSessionId }).
3. Web (DroneSession.ts):
   • Checks DB for ChatTurn status.
   • If turn is already finished, responds with { action: "discard" }.
   • If turn is processing, responds with { action: "retry" } and schedules a new processWorkOrder after a delay.
4. Drone: Deletes local cache upon receiving any crashRecoveryResponse.

---

7. Extending the Protocol

To add a new message:

1. Add the message type to packages/api/src/messages/ide.ts or drone.ts.
2. Register it in ClientToServerEvents or ServerToClientEvents in packages/api/src/messages/socket.ts.
3. Implement the sender (emit) in the Client (ide or drone).
4. Implement the handler in the corresponding CodeSession or DroneSession on the Web server.
5. Implement the forward-path routing if needed.