142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# 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
|
|
```typescript
|
|
type RequestSessionLockMessage = (
|
|
registration: IDroneRegistration,
|
|
project: IProject,
|
|
chatSession: IChatSession,
|
|
cb: (success: boolean, chatSessionId: string) => void
|
|
) => void;
|
|
|
|
type SubmitPromptMessage = (prompt: string) => void;
|
|
```
|
|
|
|
### Web -> Drone
|
|
```typescript
|
|
type ProcessWorkOrderMessage = (
|
|
registration: IDroneRegistration,
|
|
project: IProject,
|
|
chatSession: IChatSession,
|
|
turn: IChatTurn,
|
|
cb: (success: boolean, message?: string) => void
|
|
) => void;
|
|
```
|
|
|
|
### Drone -> Web (Streaming)
|
|
```typescript
|
|
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.
|