gadget/gadget-drone/docs/gadget-drone.md

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.

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

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 .gadget/workspace.json file, it refuses to start.

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

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.

.gadget directory

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 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 ChatTurn contains information such as:

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

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.

Workspace Modes

The drone's workspace directory can be in one of several mutually exclusive modes:

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