# Gadget Code Workspaces

In Gadget Code, a Workspace represents a directory that is being managed by a [gadget-drone](../gadget-drone) process. The User starts `gadget-drone` in an empty directory, or a directory that is already being managed as a `gadget-drone` Workspace. The `gadget-drone` then performs all operations within that directory, and owns it.

After the User creates or opens a [Project](../packages/api/src/interfaces/project.ts), they acquire a session lock on a gadget-drone instance, and enter the Chat Session view of [gadget-code:web](../gadget-code/frontend/). This is a Project Workspace - the project directory within the Workspace that is being worked on by a `gadget-drone` instance. This is where the User works on a Project. Project directories are named using `Project.slug`, which is why they have to be unique per-User.

The `gadget-drone` workspace can have multiple projects cloned to it, but only one project is active at a time. The gadget-drone switches from project to project based on the details received in a [requestSessionLock](../packages/api/src/messages/drone.ts) socket message.

## Workspace Modes

The `gadget-drone` process maintains a global workspace state (mode). A workspace can be in one and only one of several modes at any given moment:

- **Idle**

  The workspace isn't locked to any current operation(s).

- **Syncing**

  The `gadget-drone` instance is cloning, committing, pushing, or pulling a Project.

- **User**

  The User has locked the workspace for working on a project within the workspace.

- **Agent**

  The Gadget Code agent ("Gadget") has locked the workspace for working on files in a Project directory using it's tools in the [Agentic Workflow Loop (AWL)](../gadget-drone/docs/agentic-workflow-loop.md)

The modes are mututally exclusive. The user can't edit files while the workspace is idle, syncing, or when .

The Agent _can_ perform git operations while holding the Agent lock. The User _can_ commit changes and perform other git operations while holding the FileEdit lock. They don't have to also acquire a sync lock - they hold the lock on the whole workspace, enabling their `gadget-drone` to perform any operation needed within that mode's context.

### Mode: Idle

When the workspace is idle:

1. The User can request to lock the workspace for User mode.
2. The Agent can request to lock the workspace for Agent mode.
3. `gadget-drone` itself can request to lock the workspace for sync operations.

NO operations can be performed while in Idle mode. One of the applications' defined actors (User, Agent, `gadget-drone`) must request and hold the workspace lock before performing any operations in their assigned mode.

### Mode: Syncing

`gadget-drone` will request a workspace lock for Syncing mode operations, such as cloning a Project, committing changes, pushing to remote, or pulling from remote. These are very high-level and deterministic code operations that simply manage which projects are on disk in the workspace at any given time.

Syncing is a mode used commonly _while_ processing an Agent or User lock. When `requestSessionLock` arrives, it specifies a project. The `gadget-drone` checks to see if it has that project, if it's dirty, etc., and prepares the project directory for use. It holds the workspace in Syncing mode as it performs this work. Then, it releases the lock for the next operation to proceed.

And that will be to enter either User or Agent mode, which is where the actual code editing happens in the project workspace.

### Mode: User

When a user has locked the workspace for User mode, they can perform a variety of operations within the project. They can edit files, commit changes, push to remote, pull from remote, etc.

The User manually releases the User mode lock when they are done working, returning the workspace to Idle.

### Mode: Agent

When a work order arrives at `gadget-drone`, it will first sync the project directory, then lock the workspace for the Agent to process the prompt in the work order. The agent then uses it's tools to work on the project, performing possibly hundreds of operations while holding the lock. The agent can read, write, and delete files. It can use git and a wide variety of other commands and tools.

When the AWL finishes for this turn of processing, it releases the Agent lock, returning the workspace to Idle mode.

## Intent and Purpose

We can't let `gadget-code` run a script that deletes a project working directory while an Agent is running the AWL in that directory. We can't let an Agent change a file that the User is currently editing in the IDE. And we can't let the User do things while the system is managing directory contents or an Agent is working on them.

The above defines a Workspace lock and mutually exclusive modes that implement the controls needed to prevent those sorts of issues. This system prevents the kinds of errors and collisions that happen when multiple things are working in one project worksapce directory at the same time.

This won't prevent all conflicts. It just models how one entity works in their local "projects" directory, and pushes "merge conflicts" to the best system for handling them: git. And we want that because today's modern models are quite good at resolving them (it's a standard models can follow with mountains of available examples and discussion).
