diff --git a/.github/instructions/sessions.instructions.md b/.github/instructions/sessions.instructions.md index 88189a950f964f..cb56021ab83606 100644 --- a/.github/instructions/sessions.instructions.md +++ b/.github/instructions/sessions.instructions.md @@ -11,6 +11,76 @@ When working on files under `src/vs/sessions/`, use these skills for detailed gu - **`sessions`** skill — covers the full architecture: layering, folder structure, chat widget, menus, contributions, entry points, and development guidelines +## Architecture at a Glance + +``` +vs/sessions (Agents Window) ← this layer + ↓ imports from +vs/workbench ← standard VS Code + ↓ +vs/editor → vs/platform → vs/base +``` + +**Layer rule:** `vs/sessions` imports from `vs/workbench` and below. `vs/workbench` must **never** import from `vs/sessions`. + +**Internal layers** (see `src/vs/sessions/LAYERS.md`): +``` +Entry Points → contrib/* / contrib/providers/* / services/* → browser/ & common/ (core) +``` + +**Key constraint:** `contrib/*` must NOT import from `contrib/providers/*`. Providers are the most permissive contrib layer and may import from non-provider contribs, services, core, and sibling providers. + +## Core Services + +| Service | Interface file | Purpose | +|---------|---------------|---------| +| `ISessionsManagementService` | `services/sessions/common/sessionsManagement.ts` | Active session tracking, navigation, CRUD operations | +| `ISessionsProvidersService` | `services/sessions/common/sessionsProvider.ts` | Provider registry (register/unregister/lookup) | +| `ISession` / `IChat` | `services/sessions/common/session.ts` | Session and chat data interfaces with observable properties | + +## Key Development Patterns + +### Registering Contributions + +All features register through the contribution model and must be imported in entry points: +- `sessions.common.main.ts` — cross-platform contributions +- `sessions.desktop.main.ts` — desktop/Electron-specific +- `sessions.web.main.ts` — web-specific + +### Menu Registration + +Always use `Menus.*` from `browser/menus.ts` — never `MenuId.*` from `vs/platform/actions`: +- `Menus.TitleBarLeftLayout` / `Menus.TitleBarRightLayout` — titlebar actions +- `Menus.SidebarTitle` — sidebar header actions +- `Menus.AuxiliaryBarTitle` — auxiliary bar header actions +- `Menus.ChatBarTitle` — chat bar header actions + +### Context Keys + +All sessions-specific context keys live in `common/contextkeys.ts`: +- `IsNewChatSessionContext` — whether showing the new session view +- `ActiveSessionProviderIdContext` — which provider owns the active session +- `ActiveSessionTypeContext` — session type of the active session +- `IsPhoneLayoutContext` — whether in phone layout mode +- `ChatBarVisibleContext` / `ChatBarFocusContext` — chat bar state + +### Observable Patterns + +```typescript +// Subscribe to session state changes +this._register(autorun(reader => { + const session = this.sessionsManagementService.activeSession.read(reader); + const title = session?.title.read(reader); + // React to changes +})); + +// Batch updates +transaction(tx => { + this._title.set(newTitle, tx); + this._status.set(newStatus, tx); +}); +``` + ## Mobile Component Architecture The Agents window has an established mobile architecture (documented in `src/vs/sessions/MOBILE.md`). When adding phone-specific UI — bottom sheets, action sheets, mobile pickers, or any interaction that differs from desktop — follow these rules: @@ -34,3 +104,9 @@ The Agents window can run on touch-capable platforms (notably iOS). Follow these - Do not use `EventType.MOUSE_DOWN`, `EventType.MOUSE_UP`, or `EventType.MOUSE_MOVE` with `addDisposableListener` directly — on iOS, these events don't fire because the platform uses pointer events. Use `addDisposableGenericMouseDownListener`, `addDisposableGenericMouseUpListener`, or `addDisposableGenericMouseMoveListener` instead, which automatically select the correct event type per platform. - For custom clickable elements (e.g. picker triggers, title bar pills, or other `
`/`` elements styled as buttons) that open pickers or menus on click, listen to **both** `EventType.CLICK` and `TouchEventType.Tap` and call `Gesture.addTarget` on the element. On touch devices, including iOS, VS Code relies on the gesture system to emit `TouchEventType.Tap`, and `EventType.CLICK` alone may not reliably fire there. The base `Button` class already does this correctly, so this rule applies to custom non-`