From 88068677053f1e72295fcc2ed7ca32a401e552f3 Mon Sep 17 00:00:00 2001 From: Rob Colbert Date: Thu, 30 Apr 2026 06:03:45 -0400 Subject: [PATCH] doc update --- docs/socket-protocol.md | 153 ++++++++++++++++++++++------ gadget-drone/.gadget/workspace.json | 14 --- 2 files changed, 123 insertions(+), 44 deletions(-) delete mode 100644 gadget-drone/.gadget/workspace.json diff --git a/docs/socket-protocol.md b/docs/socket-protocol.md index 6deadc2..9322cd9 100644 --- a/docs/socket-protocol.md +++ b/docs/socket-protocol.md @@ -1,48 +1,141 @@ -# Gadget Code Socket Protocol +# Gadget Code Socket Protocol Reference -There are three primary components in the Gadget Code architecture: +This document serves as a "Cheat Sheet" for AI agents and developers working on the Gadget Code real-time messaging system. -1. gadget-code:web The backend web server and interface to the database, etc. -2. gadget-code:ide The HTML5 ReactJS client running in the browser. -3. gadget-drone The worker process that executes prompt work orders using the Agentic Workflow Loop. +## 1. Components & Connections -Socket.IO is used to connect these components and exchange messages in real-time. +| 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 | -## How It Works +--- -### Getting Into A Chat Session +## 2. Event Map Overview -1. The User starts and registers at least one gadget-drone in a workspace directory. -2. The User signs into the IDE. -3. The User creates or loads a [Project](../packages/api/src/interfaces/project.ts). -4. The User selects one of their available gadget-drone instances, and either continues an exist ChatSession, or creates a new one. -5. gadget-code:web sends the [requestSessionLock](../packages//api/src/messages/ide.ts) and locks the gadget-drone to the ChatSession in the Project. - a. The drone marks itself as locked, and will refuse all lock requests until this lock is released. - b. The drone synchronizes the project into the workspace. - c. The drone follows the project's instructions for configuring it for development/testing/production. - d. The drone grants the IDE the requested session lock. -6. gadget-code:ide navigates to the Chat Session view. +Defined in `packages/api/src/messages/socket.ts`. -The User can now begin entering prompts and editing files. +### 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. -### Editing A File +### 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. -When in the Chat Session view (see: [UI Design & Style Guide](../gadget-code/docs/ui-design-guide.md)), the User can select a file from the Files pane to open it in the File Editor. The mode of the File Editor depends on what's happening in the IDE at that time. +### Web -> Drone (Server to Client) +* `processWorkOrder`: Command to start processing a specific prompt/turn. +* `crashRecoveryResponse`: Command to `discard` or `retry` a stalled work order. -If there is a prompt work order being processed, the File Editor is read-only. The User can browse and scroll through the contents of the file and see all metadata about the file. The information and file content displayed will update as the gadget-drone process is doing it's work. But, the User is not permitted to make any changes to the displayed file content, or save the file. +--- -If the workspace is idle (no prompt is executing), then the File Editor will open in read-write mode. The User will be able to edit the file (using the ACE editor). The User will be able to save the file. The User cannot enter a prompt or create a prompt work order while the session is in file edit mode. The user must close the File Editor and return to idle +## 3. Core Sequences & Routing -## Protocol Sequences +### 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**. -### requestSessionLock +### 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. -IDE:requestSessionLock => gadget-code:web => gadget-drone => gadget-code:web => IDE +### 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. -The IDE initiates `requestSessionLock` when it wants to start working with a Chat Session. The event is received by the web server, which selects the drone for which it is intended based on the supplied DroneRegistration.\_id. The web server sends the message to the drone, which process it and returns the result to the web server. The web server sends the message back to the IDE. +--- -### requestWorkspaceMode +## 4. Message Signatures (TS Reference) -IDE:requestWorkspaceMode => gadget-code:web => gadget-drone => gadget-code:web => IDE +### IDE -> Web +```typescript +type RequestSessionLockMessage = ( + registration: IDroneRegistration, + project: IProject, + chatSession: IChatSession, + cb: (success: boolean, chatSessionId: string) => void +) => void; -The IDE initiates `requestWorkspaceMode` when it wants to request the User mode so the User can begin editing files and making changes within the project. The event is received by the web server, which sends the message to the drone. The drone processes the request and returns the result to the web server. The web server sends the message back to the IDE. +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. diff --git a/gadget-drone/.gadget/workspace.json b/gadget-drone/.gadget/workspace.json deleted file mode 100644 index 0a402a0..0000000 --- a/gadget-drone/.gadget/workspace.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "workspaceId": "3cf4240b-dc89-42e4-abc7-170f39ae0c24", - "createdAt": "2026-04-29T22:30:06.694Z", - "hostname": "mysterymachine", - "workspaceDir": "/home/rob/projects/gadget/gadget-drone", - "chatSession": null, - "lockedProject": null, - "projects": [], - "registration": { - "_id": "69f286d1deefb9cb80aacac0", - "status": "available", - "registeredAt": "2026-04-29T22:31:45.306Z" - } -} \ No newline at end of file