From 7c85c4a71d6e3bf797610e8d9976b29ed8feaf1c Mon Sep 17 00:00:00 2001 From: Rob Colbert Date: Wed, 29 Apr 2026 12:31:04 -0400 Subject: [PATCH] human draft (wip) --- docs/socket-protocol.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/socket-protocol.md diff --git a/docs/socket-protocol.md b/docs/socket-protocol.md new file mode 100644 index 0000000..8b30ae0 --- /dev/null +++ b/docs/socket-protocol.md @@ -0,0 +1,32 @@ +# Gadget Code Socket Protocol + +There are three primary components in the Gadget Code architecture: + +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. + +Socket.IO is used to connect these components and exchange messages in real-time. + +## How It Works + +### Getting Into A Chat Session + +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 in the Chat Session view. + +### Editing A File + +When in the Chat Session view (see: []()), 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. + +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