Agent Sessions Workbench Layout Specification

This document is the authoritative specification for the Agent Sessions workbench layout. All implementation changes must be reflected here, and all development work should reference this document.

1. Overview

The Agent Sessions Workbench (Workbench in sessions/browser/workbench.ts) provides a simplified, fixed layout optimized for agent session workflows. Unlike the default VS Code workbench, this layout:

• Does not support settings-based customization
• Has fixed part positions
• Excludes several standard workbench parts

2. Layout Structure

2.1 Visual Representation

┌─────────┬───────────────────────────────────────────────────────┐
│         │                    Titlebar                           │
│         ├────────────────────────────────────┬──────────────────┤
│ Sidebar │              Chat Bar              │  Auxiliary Bar   │
│         ├────────────────────────────────────┴──────────────────┤
│         │                      Panel                            │
└─────────┴───────────────────────────────────────────────────────┘

Editors open via MODAL_GROUP into the standard ModalEditorPart overlay
(created on-demand by EditorParts.createModalEditorPart). The main
editor part exists but is hidden (display:none) for future use.

2.2 Parts

Included Parts

Excluded Parts

The following parts from the default workbench are not included:

3. Titlebar Configuration

The Agent Sessions workbench uses a fully independent titlebar part (TitlebarPart) with its own title service (TitleService), implemented in sessions/browser/parts/titlebarPart.ts. This is a standalone implementation (not extending BrowserTitlebarPart) with a simple three-section layout driven entirely by menus.

3.1 Titlebar Part Architecture

The titlebar is divided into three sections, each rendered by a MenuWorkbenchToolBar:

No menubar, no editor actions, no layout controls, no WindowTitle dependency.

3.2 Command Center

The Agent Sessions titlebar includes a command center with a custom title bar widget (SessionsTitleBarWidget). It uses custom menu IDs separate from the default workbench command center to avoid conflicts:

• Menus.CommandCenter — The center toolbar menu (replaces MenuId.CommandCenter)
• Menus.TitleBarControlMenu — A submenu registered in the command center whose rendering is intercepted by IActionViewItemService to display the custom widget

The widget:

• Extends BaseActionViewItem and renders a clickable label showing the active session title
• Shows kind icon (provider type icon), session title, repository folder name, and changes summary (+insertions -deletions)
• On click, opens the AgentSessionsPicker quick pick to switch between sessions
• Gets the active session label from IActiveSessionService.getActiveSession() and the live model title from IChatService, falling back to "New Session" if no active session is found
• Re-renders automatically when the active session changes via autorun on IActiveSessionService.activeSession, and when session data changes via IAgentSessionsService.model.onDidChangeSessions
• Is registered via SessionsTitleBarContribution (an IWorkbenchContribution in contrib/sessions/browser/sessionsTitleBarWidget.ts) that calls IActionViewItemService.register() to intercept the submenu rendering

3.3 Left Toolbar

The Agent Sessions titlebar includes a custom left toolbar that appears after the app icon. This toolbar:

• Uses Menus.TitleBarLeft for its actions
• Uses HiddenItemStrategy.NoHide so actions cannot be hidden by users
• Displays actions registered to Menus.TitleBarLeft

3.4 Titlebar Actions

The toggle sidebar action:

• Shows layoutSidebarLeft icon when sidebar is visible
• Shows layoutSidebarLeftOff icon when sidebar is hidden
• Bound to Ctrl+B / Cmd+B keybinding
• Announces visibility changes to screen readers

The Run Script action:

• Displayed as a split button via RunScriptDropdownMenuId submenu on Menus.TitleBarRight
• Primary action runs the configured script command in a terminal
• Dropdown includes "Configure Run Action..." to set/change the script
• Registered in contrib/chat/browser/runScriptAction.ts

The Open... action:

• Displayed as a split button via Menus.OpenSubMenu on Menus.TitleBarRight
• Contains "Open Terminal" (opens terminal at session worktree) and "Open in VS Code" (opens worktree in new VS Code window)
• Registered in contrib/chat/browser/chat.contribution.ts

3.5 Panel Title Actions

The panel title bar includes actions for controlling the panel:

3.6 Account Widget

The account widget has been moved from the titlebar to the sidebar footer. It is rendered as a custom AccountWidget action view item:

• Registered in contrib/accountMenu/browser/account.contribution.ts
• Uses the Menus.SidebarFooter menu
• Shows account button with sign-in/sign-out and an update button when an update is available
• Account menu shows signed-in user label from IDefaultAccountService (or Sign In), Sign Out, Settings, and Check for Updates

4. Grid Structure

The layout uses SerializableGrid from vs/base/browser/ui/grid/grid.js.

4.1 Grid Tree

The Editor part is not in the grid — it is rendered as a modal overlay (see Section 4.3).

Orientation: HORIZONTAL (root)
├── Sidebar (leaf, size: 300px default)
└── Right Section (branch, VERTICAL, size: remaining width)
    ├── Titlebar (leaf, size: titleBarHeight)
    ├── Top Right (branch, HORIZONTAL, size: remaining height - panel)
    │   ├── Chat Bar (leaf, size: remaining width)
    │   └── Auxiliary Bar (leaf, size: 300px default)
    └── Panel (leaf, size: 300px default, hidden by default)

This structure places the sidebar at the root level spanning the full window height. The titlebar, chat bar, auxiliary bar, and panel are all within the right section.

4.2 Default Sizes

4.3 Editor Modal

The main editor part is created but hidden (display:none). It exists for future use but is not currently visible. All editors are forced to open in the ModalEditorPart overlay via the standard createModalEditorPart() mechanism.

How It Works

The sessions configuration sets workbench.editor.useModal to 'all' (in contrib/configuration/browser/configuration.contribution.ts). This causes findGroup() in editorGroupFinder.ts to redirect all editor opens (that do not specify an explicit preferred group) to createModalEditorPart(), which creates the standard workbench ModalEditorPart overlay on-demand.

When the setting is 'all':

• All editors without an explicit preferred group open in the modal editor part
• The modal is not auto-closed when editors open without explicit MODAL_GROUP as preferred group

Behavior

Configuration

The setting workbench.editor.useModal is an enum with three values:

• 'off': Editors never open in a modal overlay
• 'some': Certain editors (e.g. Settings, Keyboard Shortcuts) may open in a modal overlay when requested via MODAL_GROUP
• 'all': All editors open in a modal overlay (used by sessions window)

5. Feature Support Matrix

6. API Reference

6.1 Part Visibility

// Check if a part is visible
isVisible(part: Parts): boolean

// Show or hide a part
setPartHidden(hidden: boolean, part: Parts): void

Behavior:

• Hiding a part also hides its active pane composite
• Showing a part restores the last active pane composite
• Panel Part:
  • If the panel is maximized when hiding, it exits maximized state first
• Editor Part:
  • The main editor part is always hidden (display:none); setEditorHidden() is a no-op
  • All editors open via MODAL_GROUP into the ModalEditorPart overlay, which manages its own lifecycle

6.2 Part Sizing

// Get current size of a part
getSize(part: Parts): IViewSize

// Set absolute size of a part
setSize(part: Parts, size: IViewSize): void

// Resize by delta values
resizePart(part: Parts, sizeChangeWidth: number, sizeChangeHeight: number): void

6.3 Focus Management

// Focus a specific part
focusPart(part: Parts): void

// Check if a part has focus
hasFocus(part: Parts): boolean

// Focus the Chat Bar (default focus target)
focus(): void

6.4 Container Access

// Get the main container or active container
get mainContainer(): HTMLElement
get activeContainer(): HTMLElement

// Get container for a specific part
getContainer(targetWindow: Window, part?: Parts): HTMLElement | undefined

6.5 Layout Offset

// Get offset info for positioning elements
get mainContainerOffset(): ILayoutOffsetInfo
get activeContainerOffset(): ILayoutOffsetInfo

Returns { top, quickPickTop } where top is the titlebar height.

7. Events

Events that never fire (unsupported features):

• onDidChangeZenMode
• onDidChangeMainEditorCenteredLayout
• onDidChangePanelAlignment
• onDidChangePanelPosition
• onDidChangeAuxiliaryBarMaximized

8. CSS Classes

8.1 Visibility Classes

Applied to mainContainer based on part visibility:

8.2 Window State Classes

8.3 Platform Classes

Applied during workbench render:

• monaco-workbench
• agent-sessions-workbench
• windows / linux / mac
• web (if running in browser)
• chromium / firefox / safari

9. Agent Session Parts

The Agent Sessions workbench uses specialized part implementations that extend the base pane composite infrastructure but are simplified for agent session contexts.

9.1 Part Classes

9.2 Key Differences from Standard Parts

9.3 Part Creation

The agent sessions pane composite parts are created and registered via the AgenticPaneCompositePartService in sessions/browser/paneCompositePartService.ts. This service is registered as a singleton for IPaneCompositePartService and directly instantiates each part:

// In AgenticPaneCompositePartService constructor
this.registerPart(ViewContainerLocation.Panel, instantiationService.createInstance(PanelPart));
this.registerPart(ViewContainerLocation.Sidebar, instantiationService.createInstance(SidebarPart));
this.registerPart(ViewContainerLocation.AuxiliaryBar, instantiationService.createInstance(AuxiliaryBarPart));
this.registerPart(ViewContainerLocation.ChatBar, instantiationService.createInstance(ChatBarPart));

This architecture ensures that:

1. The agent sessions workbench uses its own part implementations rather than the standard workbench parts
2. Each part is instantiated eagerly in the constructor, as the service delegates all operations to the appropriate part by ViewContainerLocation

9.4 Storage Keys

Each agent session part uses separate storage keys to avoid conflicts with regular workbench state:

9.5 Part Borders and Card Appearance

Parts manage their own border and background styling via the updateStyles() method. The auxiliary bar and panel use a card appearance with CSS variables for background and border:

9.6 Auxiliary Bar Run Script Dropdown

The AuxiliaryBarPart provides a custom DropdownWithPrimaryActionViewItem for the run script action (workbench.action.agentSessions.runScript). This is rendered as a split button with:

• Primary action: Runs the main script action
• Dropdown: Shows additional actions from the AgentSessionsRunScriptDropdown menu
• The dropdown menu is created from MenuId.for('AgentSessionsRunScriptDropdown') and updates dynamically when menu items change

9.7 Sidebar Footer

The SidebarPart includes a footer section (35px height) positioned below the pane composite content. The sidebar uses a custom layout() override that reduces the content height by FOOTER_HEIGHT and renders a MenuWorkbenchToolBar driven by Menus.SidebarFooter. The footer hosts the account widget (see Section 3.6).

On macOS native with custom titlebar, the sidebar title area includes a traffic light spacer (70px) to push content past the system window controls. The spacer is hidden in fullscreen mode and is not created when using native titlebar (since the OS renders traffic lights in its own title bar).

10. Workbench Contributions

The Agent Sessions workbench registers contributions via module imports in sessions.desktop.main.ts (and sessions.common.main.ts). Key contributions:

Additionally, BranchChatSessionAction is registered in contrib/chat/browser/chat.contribution.ts.

10.1 Changes View

The Changes view is registered in contrib/changesView/browser/changesView.contribution.ts:

• Container: CHANGES_VIEW_CONTAINER_ID in ViewContainerLocation.AuxiliaryBar (default, hidden if empty)
• View: CHANGES_VIEW_ID with ChangesViewPane
• Window visibility: WindowVisibility.Sessions (only visible in agent sessions workbench)

10.2 Sessions View

The Sessions view is registered in contrib/sessions/browser/sessions.contribution.ts:

• Container: Sessions container in ViewContainerLocation.Sidebar (default)
• View: SessionsViewId with AgenticSessionsViewPane
• Window visibility: WindowVisibility.Sessions

11. File Structure

src/vs/sessions/
├── README.md                               # Layer specification
├── LAYOUT.md                               # This specification
├── AI_CUSTOMIZATIONS.md                    # AI customization design document
├── sessions.common.main.ts                 # Common entry point (browser + desktop)
├── sessions.desktop.main.ts                # Desktop entry point (imports all contributions)
├── common/
│   └── contextkeys.ts                      # ChatBar context keys
├── browser/                                # Core workbench implementation
│   ├── workbench.ts                        # Main layout implementation (Workbench class)
│   ├── menus.ts                            # Agent sessions menu IDs (Menus export)
│   ├── layoutActions.ts                    # Layout actions (toggle sidebar, secondary sidebar, panel)
│   ├── paneCompositePartService.ts         # AgenticPaneCompositePartService
│   ├── style.css                           # Layout-specific styles
│   ├── widget/                             # Agent sessions chat widget
│   │   ├── AGENTS_CHAT_WIDGET.md           # Chat widget architecture documentation
│   │   ├── agentSessionsChatWidget.ts      # Main chat widget wrapper
│   │   ├── agentSessionsChatTargetConfig.ts # Target configuration (observable)
│   │   ├── agentSessionsTargetPickerActionItem.ts # Target picker for input toolbar
│   │   └── media/
│   │       └── agentSessionsChatWidget.css
│   └── parts/
│       ├── titlebarPart.ts                 # Simplified titlebar part, MainTitlebarPart, AuxiliaryTitlebarPart, and TitleService
│       ├── sidebarPart.ts                  # Agent session sidebar (with footer and macOS traffic light spacer)
│       ├── auxiliaryBarPart.ts             # Agent session auxiliary bar (with run script dropdown)
│       ├── panelPart.ts                    # Agent session panel
│       ├── chatBarPart.ts                  # Chat Bar part implementation
│       ├── projectBarPart.ts              # Project bar part (folder entries, icon customization)
│       ├── parts.ts                        # AgenticParts enum
│       ├── agentSessionsChatInputPart.ts   # Chat input part adapter
│       ├── agentSessionsChatWelcomePart.ts # Chat welcome part
│       └── media/
│           ├── titlebarpart.css
│           ├── sidebarPart.css
│           ├── chatBarPart.css
│           ├── projectBarPart.css
│           └── agentSessionsChatWelcomePart.css
├── electron-browser/                       # Desktop-specific entry points
│   ├── sessions.main.ts
│   ├── sessions.ts
│   ├── sessions.html
│   └── sessions-dev.html
├── contrib/                                # Feature contributions
│   ├── accountMenu/browser/                # Account menu widget for sidebar footer
│   │   ├── account.contribution.ts
│   │   └── media/
│   ├── aiCustomizationManagement/browser/  # AI customization management editor
│   ├── aiCustomizationTreeView/browser/    # AI customization tree view sidebar
│   ├── changesView/browser/                # File changes view
│   │   ├── changesView.contribution.ts
│   │   ├── changesView.ts
│   │   └── media/
│   ├── chat/browser/                       # Chat actions and services
│   │   ├── chat.contribution.ts            # Open in VS Code, Open Terminal, branch chat, run script, prompts service
│   │   ├── branchChatSessionAction.ts      # Branch chat session action
│   │   ├── runScriptAction.ts              # Run script contribution and split button
│   │   └── promptsService.ts              # Agentic prompts service override
│   ├── configuration/browser/              # Configuration contribution
│   │   └── configuration.contribution.ts
│   └── sessions/browser/                   # Sessions view and title bar widget
│       ├── sessions.contribution.ts        # Sessions view container, view, and title bar widget registration
│       ├── sessionsViewPane.ts             # Sessions list view pane
│       ├── sessionsTitleBarWidget.ts       # Title bar widget (SessionsTitleBarWidget, SessionsTitleBarContribution)
│       ├── activeSessionService.ts         # IActiveSessionService implementation
│       └── media/
│           └── sessionsTitleBarWidget.css

12. Implementation Requirements

When modifying the Agent Sessions layout:

1. Maintain fixed positions — Do not add settings-based position customization
2. Panel must span the right section width — The grid structure places the panel below Chat Bar and Auxiliary Bar only
3. Sidebar spans full window height — Sidebar is at the root grid level, spanning from top to bottom independently of the titlebar
4. New parts go in right section — Any new parts should be added to the right section alongside Titlebar, Chat Bar, and Auxiliary Bar
5. Update this spec — All changes must be documented here
6. Preserve no-op methods — Unsupported features should remain as no-ops, not throw errors
7. Handle pane composite lifecycle — When hiding/showing parts, manage the associated pane composites
8. Use agent session parts — New functionality for parts should be added to the agent session part classes, not the standard parts

13. Lifecycle

13.1 Startup Sequence

1. constructor() — Register error handlers
2. startup() — Initialize services and layout
3. initServices() — Set up service collection (including TitleService), register singleton services, set lifecycle to Ready
4. initLayout() — Get services, register layout listeners
5. renderWorkbench() — Create DOM, create parts, create hidden editor part, set up notifications
6. createWorkbenchLayout() — Build the grid structure
7. createWorkbenchManagement() — (No-op in agent sessions layout)
8. layout() — Perform initial layout
9. restore() — Restore parts (open default view containers), set lifecycle to Restored, then Eventually

Note: Contributions are registered via module imports in sessions.desktop.main.ts (through registerWorkbenchContribution2, registerAction2, registerSingleton calls), not via a central registration function.

13.2 Part Restoration

During the restore() phase, restoreParts() is called to open the default view container for each visible part:

private restoreParts(): void {
    const partsToRestore = [
        { location: ViewContainerLocation.Sidebar, visible: this.partVisibility.sidebar },
        { location: ViewContainerLocation.Panel, visible: this.partVisibility.panel },
        { location: ViewContainerLocation.AuxiliaryBar, visible: this.partVisibility.auxiliaryBar },
        { location: ViewContainerLocation.ChatBar, visible: this.partVisibility.chatBar },
    ];

    for (const { location, visible } of partsToRestore) {
        if (visible) {
            const defaultViewContainer = this.viewDescriptorService.getDefaultViewContainer(location);
            if (defaultViewContainer) {
                this.paneCompositeService.openPaneComposite(defaultViewContainer.id, location);
            }
        }
    }
}

This ensures that when a part is visible, its default view container is automatically opened and displayed.

13.3 State Tracking

interface IPartVisibilityState {
    sidebar: boolean;
    auxiliaryBar: boolean;
    editor: boolean;
    panel: boolean;
    chatBar: boolean;
}

Initial state:

14. Sidebar Reveal Buttons

Note: Sidebar reveal buttons (SidebarRevealButton) have been removed from the implementation. The corresponding file parts/sidebarRevealButton.ts no longer exists. Sidebar visibility is controlled via the toggle actions in the titlebar (see Section 3.4).

Revision History