dtp/gadget
1
0
Fork 0
Code Actions Packages Projects Releases Activity
1b8044a8a7
gadget/gadget-drone/docs/gadget-drone.md
Rob Colbert 1edc3a85b8 created by merging gadget-code and gadget-drone
2026-04-28 09:20:37 -04:00

3.1 KiB
Raw Blame History

Gadget Drone

Gadget Drone is a worker component in the Gadget Code ecosystem. It is built and maintained separately from this project. Gadget Drone operates as a standalone process running on a host in a directory of the User's choosing.

The User can operate more than one Gadget Drone per host by running them in separate Gadget Drone Workspace Directories.

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.

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 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.

Startup Procedure

At startup, Gadget Drone:

  1. Attempts to take ownership of process.cwd() as a Gadget Drone Workspace Directory. A workspace will contain clones of git repositories stored in directories matching the Project.slug.

    , and verifies that:

    1. The directory is already a workspace directory; or
    2. 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.

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.

ChatSession and ChatHistory

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.

A ChatSession turn equals one ChatHistory record in the database, and is made of:

  1. The User's input prompt
  2. The Agent's Thinking content
  3. The Agent's Response content
  4. All tool calls made by the Agent, to include:
    1. The name of the tool function being called
    2. The input parameters to the tool call
    3. The response from the tool call

Gadget Drone:

.gadget directory

When the Gadget Drone starts and initializes,

.gadget-cache directory