dtp/gadget
1
0
Fork 0
Code Actions Packages Projects Releases Activity
5c56f95cd6
gadget/docs/workspace-management.md
Rob Colbert 5c56f95cd6 Implement workspace mode switching with validation 
- Add isProcessingWorkOrder flag to track Agent work order processing
- Update onRequestWorkspaceMode with mode transition matrix validation
  - Idle → User/Agent: Always allowed
  - User → Agent: Always allowed (file editor checks for future)
  - Agent → User: Only if !isProcessingWorkOrder
  - All other transitions: Rejected with reason
- Extend RequestWorkspaceModeCallback with optional reason parameter
- Update frontend socket client to capture rejection reason
- Update handleWorkspaceModeChange to display rejection reason in toast
- Update WorkspaceModeIndicator to allow mode transitions per matrix
- Fix FilesPanel RW/RO indicator swap bug
- Document mode transition matrix and behavior in workspace-management.md
2026-05-02 18:13:31 -04:00

128 lines
8.5 KiB
Markdown
Raw Blame History

# Workspace Management
Consider [The Architecture](./architecture.md) and the [Socket Protocol](./socket-protocol.md).
Ignore details unrelated to the Chat Session view such as the Project Manager and Home views. We are focusing on getting a user's prompt from the IDE to gadget-drone, and into the Agentic Workflow Loop to be processed by a Large Language Model using configuration information from the work order such as the system prompt, user prompt, service provider/API specification, and which model id to request.
## The Session Lock And Workspace Modes
The IDE first locks the selected drone to a project and chat session within it using `requestSessionLock`. At this point, the drone's workspace mode is set to: `Idle`. The drone has locked to the User's `ChatSession` within the `Project`, and has set it's workspace mode to Idle. The drone is now ready to begin doing work in the project directory within the workspace.
## Workspace Modes
A drone's workspace can be in one of four modes:
1. Idle - the workspace is available to enter any other mode
2. Syncing - the workspace is performing a system operation
3. User - the User is working within the workspace (locks out Agent)
4. Agent - the Agent is working within the workspace (locks out User)
## Workspace Mode Control
The User uses controls provided in the IDE (see below) to request workspace mode changes, and the drone either accepts or rejects them. The drone's current workspace mode controls the availability of features in the IDE, enabling and disabling them as needed to enforce the rules of the workspace mode.
Work can be done by either the User or the Agent. Work can't be done by both at the same time. Drone workspace modes are **mutually exclusive**.
The User will use controls in the IDE to request one of two different workspace modes at a time:
1. User
2. Agent
When the workspace is **Idle**, the User can request **User** or **Agent** mode to unlock that mode's associated features.
- `User` mode unlocks read/write in the File Editor, and allows the user to hand-edit files in the project, and change the project's state.
- `Agent` mode unlocks prompt input and the creation of work orders.
In User mode, the User may open files in read/write mode, make changes to file contents, save files back to the project, and otherwise change the project's state (run builds, perform git operations, etc.). We are NOT implementing those features or the Files panel at this time. We are only implementing mode management.
In `Agent` mode, the User can submit prompts to the Agent that become work orders submitted to the drone for processing in the project directory. The user can also open files to view them in read-only mode, but can't save them back to the project workspace on disk or change the project's state while the Agent is working. We are implementing the ability to submit a prompt. We are not implementing the Files panel or opening files in read-only mode. We're just focusing on workspace management, and submitting a prompt.
## Chat Session View Changes
In the Chat Session view, we are adding flex-right justified interactive elements to the header area of the Session panel. There will be four square button indicators placed here:
1. I - Idle
2. S - Syncing
3. U - User
4. A - Agent
### Workspace Mode Indicators
The indicator is a square with a thin dark gray border that contains the letter of that mode (I, S, U, A). When inactive, the letter matches the dark gray border. When active, the letter strobes green matching the status indicator's green and strobe behavior in the application status bar's online status indicator.
At a glance, the User sees which workspace mode is currently active by observing the strobing bright-green mode indicator.
As for styling, think of audio gear - like a modern mixing console - with indicators for mute, solo, etc. These should look and work exactly like those, and it would be great if they could appear "depressed" while active as if they were "pushed" into being active, and "pop up" when not active. This is their tactility. The User should feel like they are manipulating expensive studio equipment.
### Changing Modes
The User changes workspace modes by clicking the mode indicator buttons in the SESSION panel header. Mode transitions follow a strict matrix enforced by both the IDE (UI) and the drone (backend validation).
#### Mode Transition Matrix
| Current Mode | Target Mode | Allowed? | Validation |
|--------------|-------------|----------|------------|
| Idle | User | ✅ Yes | Always allowed |
| Idle | Agent | ✅ Yes | Always allowed |
| User | Agent | ✅ Yes | Always allowed |
| User | Idle | ❌ No | Blocked by UI (no defined circumstances to return to Idle) |
| Agent | User | ⚠️ Conditional | Rejected if Agent is processing a work order |
| Agent | Idle | ❌ No | Blocked by UI (no defined circumstances to return to Idle) |
| Any | Syncing | ❌ No | System-controlled only (git operations) |
#### Mode Switch Request Flow
1. User clicks a mode indicator button (U or A)
2. IDE validates the transition is allowed (see matrix above)
3. IDE sends `requestWorkspaceMode` message to the drone
4. Drone validates the request against current state:
- **Idle → User/Agent**: Always accepted
- **User → Agent**: Always accepted (file editor checks to be added later)
- **Agent → User**: Rejected if `isProcessingWorkOrder === true` with message: "Agent is currently working. Please wait for the current task to complete."
5. Drone responds with `(success: boolean, mode: WorkspaceMode, reason?: string)`
6. If rejected, IDE displays the rejection reason as a toast notification
7. If accepted, drone emits `workspaceModeChanged` event and IDE updates UI
#### Workspace Mode Behavior
- **Idle**: Initial state after `requestSessionLock`. User can transition to User or Agent mode.
- **User**: User can work with files in read/write mode (File Editor to be implemented). Can transition to Agent mode.
- **Agent**: Agent is working or available to accept work orders. User can submit prompts. Can transition to User mode only if no work order is processing.
- **Syncing**: System-controlled state during git operations (clone, push, pull, etc.). Not user-selectable.
#### Important Notes
- The workspace **does not** automatically return to Idle after the Agentic Workflow Loop completes
- The workspace remains in the current mode until the User explicitly requests a change
- The Agent **cannot** change the workspace mode; only the User can request mode changes
- When the Agent is processing a work order (from prompt submission until `workOrderComplete` event), mode switches from Agent → User are rejected
- Rejection messages are displayed as toast notifications in the IDE
### IDE Workspace Mode Features
When the drone's workspace is in `Agent` mode:
1. The Chat View enables the prompt input and the ability to submit prompts for processing by the Agentic Workflow Loop on the drone, and the drone will accept them for processing.
2. The Files panel locks into read-only mode and updates to indicate this status in the header.
There should be no way at all to submit a prompt when the drone's workspace is NOT in `Agent` mode. The prompt input bar (text input, button, the whole panel) should be completely disabled and the placeholder for the text input should be, "Select Agent mode to enter a prompt." The User will have to select `Agent` mode to enable the controls and enter a prompt.
When the drone's workspace is in `User` mode:
1. The chat input panel disables and changes the placeholder to read, "Select Agent mode to enter a prompt."
2. The Files panel updates to indicate read-write mode
For now, this is effectively a dead mode and the User can't really do anything. We will be adding User-mode features later.
## Files Panel
In the Chat Session view, in the right sidebar, below PROJECT, we **are** adding the FILES panel mockup. This is a placeholder for now.
We are adding two indicators to the FILES panel header: RW and RO.
The indicators are consistent with the workspace mode indicators added to the header of SESSION. And, when the Files panel is in read-only mode, the RO indicator becomes active. When the Files panel is in read-write mode, the RW indicator becomes active.
The User can then know at a glance whether their files are read-only, or whether they can open and edit a file.
We are not implementing file trees or displays. We are not adding the file editor. We are only adding the Files panel with a placeholder message in it's file tree display area (or mock content), and the header with the specified indicators that _do_ react to workspace mode changes appropriately.
View Git Blame Copy Permalink