dtp/gadget
1
0
Fork 0
Code Actions Packages Projects Releases Activity

drone doc updates

Browse Source
This commit is contained in:
Rob Colbert 2026-05-02 03:13:25 -04:00
parent 4642609d06
commit 4075a63aea
2 changed files with 40 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
gadget-code/docs/gadget-drone.md
View File

@ -1,13 +0,0 @@
# Gadget Drone
Gadget Drone is a component in the Gadget Code ecosystem that operates as a headless/non-interactive process on a host in a directory on storage (once authenticated). Gadget Drone:
1. Assumes ownership of process.cwd() on startup, and verifies that the directory is either already a Gadget Drone directory, or empty. If not a Gadget Drone directory, and if also not empty, Gadget Drone refuses to start with a message printed to the console, and terminates.
2. Creates the .gadget and .gadget-cache directories in the directory on launch if they are not there.
## .gadget directory
When the Gadget Drone starts and initializes,
## .gadget-cache directory

51
gadget-drone/docs/gadget-drone.md
View File

@ -4,13 +4,15 @@ Gadget Drone is a worker component in the Gadget Code ecosystem. It is built and
The User can operate more than one Gadget Drone per host by running them in separate Gadget Drone Workspace Directories. The User can operate more than one Gadget Drone per host by running them in separate Gadget Drone Workspace Directories.
Commands are sent from the gadget-code:web to the gadget-drone process as a Socket message. The drone processes the message, and will emit status and update events as it works. These status and update events are sent to the gadget-code:web service, where they are processed into a `ChatHistory` record as part of a `ChatSession` being operated by the User in an HTML5 browser client.
## Workspace Directory ## Workspace Directory
A Gadget Drone Workspace Directory is simply `process.cwd()` at startup. It is the directory in which the drone has been started. The drone will manage the contents of the directory, and expects the directory to be empty the first time the drone is started. A Gadget Drone Workspace Directory is simply `process.cwd()` at startup. It is the directory in which the drone has been started. The drone will manage the contents of the directory, and expects the directory to be empty the first time the drone is started.
If the workspace directory isn't empty at startup, and the directory doesn't contain the `.gadget` subdirectory with a stored `.registration.json`, it refuses to start. If the workspace directory isn't empty at startup, and the directory doesn't contain the `.gadget` subdirectory with a stored `.gadget/workspace.json` file, it refuses to start.
If the directory is already a workspace directory, the drone reads the `.registration.json` file and uses that information to connect to the Gadget Code web service. If the directory is already a workspace directory, the drone reads the `.gadget/workspace.json` file and uses that information to continue initialization.
## Startup Procedure ## Startup Procedure
@ -24,19 +26,27 @@ At startup, Gadget Drone:
If not a Gadget Drone directory, and if also not empty, Gadget Drone refuses to start with a message printed to the console, and terminates. If not a Gadget Drone directory, and if also not empty, Gadget Drone refuses to start with a message printed to the console, and terminates.
2. Creates the `.gadget` and `.gadget-cache` directories in the directory on launch if they are not there. 2. Creates the `.gadget` and `.gadget/cache` directories in the directory on launch if they are not there.
It authenticates to the Gadget Code web service, receives a `DroneRegistration` and `DroneSocketSession`, connects to the Socket.IO session, and waits for commands. It authenticates to the Gadget Code web service, receives a `DroneRegistration` and `DroneSocketSession`, connects to the Socket.IO session, and waits for commands.
Commands are sent from the Gadget Code web server to the Gadget Drone process as a Socket message. The drone processes the message, and will emit status and update events as it works. These status and update events are sent to the Gadget Code web service, where they are processed into a `ChatHistory` record as part of a `ChatSession` being operated by the User in an HTML5 browser client. ## `.gadget` directory
## `ChatSession` and `ChatHistory` When the Gadget Drone starts and initializes, it will first look for the .gadget directory and configure itself based on the information contained in various files it uses during operation. If the directory does not exist, the drone creates it and initializes it with gadget-drone files that are required for normal operation.
## `.gadget/cache` directory
The gadget-drone process will write files to `.gadget/cache` as needed during normal operation. An example is the current work order in case of a crash to support crash recovery.
Agents also have tools like fetch_url that will fetch content from the Internet. Web content is converted to Markdown with line numbers, and written to .gadget/cache. From there, the agent essentially has file_read with line number offsets, limits, etc.
## `ChatSession` and `ChatTurn`
The User will enter prompts to be processed by the Gadget Code Agent, which runs in Gadget Done. One message the system sends to Gadget Drone is `prompt`, which is a message containing all details needed to execute a prompt, such as the project in which the prompt is being executed, and other details. The User will enter prompts to be processed by the Gadget Code Agent, which runs in Gadget Done. One message the system sends to Gadget Drone is `prompt`, which is a message containing all details needed to execute a prompt, such as the project in which the prompt is being executed, and other details.
The drone then executes the prompt in the project's directory to work on the project, emitting updates as it streams the response from the AI API in use, and sending a `prompt-finished` message upon completion to close out the `ChatSession` turn. The drone then executes the prompt in the project's directory to work on the project, emitting updates as it streams the response from the AI API in use, and sending a `prompt-finished` message upon completion to close out the `ChatTurn`.
A `ChatSession` turn equals one `ChatHistory` record in the database, and is made of: A `ChatTurn` contains information such as:
1. The User's input prompt 1. The User's input prompt
2. The Agent's Thinking content 2. The Agent's Thinking content
@ -46,10 +56,29 @@ A `ChatSession` turn equals one `ChatHistory` record in the database, and is mad
2. The input parameters to the tool call 2. The input parameters to the tool call
3. The response from the tool call 3. The response from the tool call
Gadget Drone: As the drone emits updates and status events, they will be recorded to the `ChatTurn` document by gadget-code:web, and forwarded to gadget-code:frontend (the IDE) for display and observation.
## `.gadget` directory ## Workspace Modes
When the Gadget Drone starts and initializes, The drone's workspace directory can be in one of several mutually exclusive modes:
## `.gadget-cache` directory - Idle
- Syncing
- Agent
- User
### Workspace Mode: Idle
The workspace is ready to do work for either the User or the Agent.
### Workspace Mode: Syncing
The workspace is running a synchronizing operation such as git clone, pull, push, etc.
### Workspace Mode: Agent
The workspace has been locked for processing a work order (prompt) in a project within the worksapce.
### Workspace Mode: User
The workspace has been locked for the User to edit files within the workspace in the IDE's file editor.