Copilot instructions

1---
2description: Architecture documentation for the Agents window — an agents-first app built as a new top-level layer alongside vs/workbench. Covers layout, parts, chat widget, contributions, entry points, and development guidelines. Use when working in `src/vs/sessions`
3applyTo: src/vs/sessions/**
4---
5 
6# Agents Window
7 
8The Agents window is a **standalone application** built as a new top-level layer (`vs/sessions`) in the VS Code architecture. It provides an agents-first experience optimized for agent workflows — a simplified, fixed-layout workbench where chat is the primary interaction surface and editors appear as modal overlays.
9 
10When working on files under `src/vs/sessions/`, use these skills for detailed guidance:
11 
12- **`sessions`** skill — covers the full architecture: layering, folder structure, chat widget, menus, contributions, entry points, and development guidelines
13 
14## Architecture at a Glance
15 
16```
17vs/sessions (Agents Window)  ← this layer
18    ↓ imports from
19vs/workbench                 ← standard VS Code
20    ↓
21vs/editor → vs/platform → vs/base
22```
23 
24**Layer rule:** `vs/sessions` imports from `vs/workbench` and below. `vs/workbench` must **never** import from `vs/sessions`.
25 
26**Internal layers** (see `src/vs/sessions/LAYERS.md`):
27```
28Entry Points → contrib/* / contrib/providers/* / services/* → browser/ & common/ (core)
29```
30 
31**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.
32 
33## Core Services
34 
35| Service | Interface file | Purpose |
36|---------|---------------|---------|
37| `ISessionsManagementService` | `services/sessions/common/sessionsManagement.ts` | Active session tracking, navigation, CRUD operations |
38| `ISessionsProvidersService` | `services/sessions/common/sessionsProvider.ts` | Provider registry (register/unregister/lookup) |
39| `ISession` / `IChat` | `services/sessions/common/session.ts` | Session and chat data interfaces with observable properties |
40 
41## Key Development Patterns
42 
43### Registering Contributions
44 
45All features register through the contribution model and must be imported in entry points:
46- `sessions.common.main.ts` — cross-platform contributions
47- `sessions.desktop.main.ts` — desktop/Electron-specific
48- `sessions.web.main.ts` — web-specific
49 
50### Menu Registration
51 
52Always use `Menus.*` from `browser/menus.ts` — never `MenuId.*` from `vs/platform/actions`:
53- `Menus.TitleBarLeftLayout` / `Menus.TitleBarRightLayout` — titlebar actions
54- `Menus.SidebarTitle` — sidebar header actions
55- `Menus.AuxiliaryBarTitle` — auxiliary bar header actions
56- `Menus.ChatBarTitle` — chat bar header actions
57 
58### Context Keys
59 
60All sessions-specific context keys live in `common/contextkeys.ts`:
61- `IsNewChatSessionContext` — whether showing the new session view
62- `SessionProviderIdContext` — which provider owns the session in scope (the active session globally)
63- `SessionTypeContext` — session type of the session in scope (the active session globally)
64- `IsPhoneLayoutContext` — whether in phone layout mode
65- `ChatBarVisibleContext` / `ChatBarFocusContext` — chat bar state
66 
67### Observable Patterns
68 
69```typescript
70// Subscribe to session state changes
71this._register(autorun(reader => {
72    const session = this.sessionsManagementService.activeSession.read(reader);
73    const title = session?.title.read(reader);
74    // React to changes
75}));
76 
77// Batch updates
78transaction(tx => {
79    this._title.set(newTitle, tx);
80    this._status.set(newStatus, tx);
81});
82```
83 
84## Mobile Component Architecture
85 
86The 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:
87 
881. **Never add `IsPhoneLayoutContext` branching inside a desktop component.** Desktop code must have zero phone-layout checks. If a component needs different behavior on phone, create a mobile subclass or a phone-gated contribution instead.
89 
902. **Create mobile subclasses in `browser/parts/mobile/`.** Extend the desktop class, override only the methods that differ (e.g., the picker/menu method), and keep the rest inherited. Examples: `MobileChatBarPart`, `MobileSidebarPart`, `MobilePanelPart`.
91 
923. **Use conditional instantiation.** The call site that creates the component (e.g., `AgenticPaneCompositePartService`) should pick the mobile vs. desktop class based on viewport width at construction time — the same pattern already used for Part subclasses.
93 
944. **Co-locate component CSS with its TypeScript file.** Each component should own its CSS in a `media/` subfolder next to the component, imported directly in the TypeScript file via `import './media/myComponent.css';`. Do not put component-specific styles in `mobileChatShell.css` — that file should contain only layout and shell-level styles for phone layout (`phone-layout` class rules).
95 
965. **Prefer reusable mobile widgets.** Before hand-rolling a bottom sheet, check if an existing pattern (panel sheet, context menu action sheet, quick pick) can be reused or extended. If a new pattern is genuinely needed, build it as a reusable widget in `browser/parts/mobile/` so other features can share it.
97 
986. **Phone-specific contributions** use `when: IsPhoneLayoutContext` in their registration and live in separate files — giving full file separation with no internal branching.
99 
100## Touch & iOS Compatibility
101 
102The Agents window can run on touch-capable platforms (notably iOS). Follow these rules for all DOM interaction code:
103 
104- 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.
105- For custom clickable elements (e.g. picker triggers, title bar pills, or other `<div>`/`<span>` 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-`<button>` trigger elements.
106- Add `touch-action: manipulation` in CSS on custom clickable elements (e.g. picker triggers, title bar pills, or other `<div>`/`<span>` elements styled as buttons) to eliminate the 300ms tap delay on touch devices. This is not needed for native `<button>` elements or standard VS Code widgets (quick picks, context menus, action bar items) which already handle touch behavior.
107 
108## DOM Traversal & Intent
109 
110Do **not** reverse-engineer user intent or component relationships by walking the DOM. Avoid `Element.closest()`, `Element.matches()`, manual `parentElement`/`parentNode` walking, and `contains()`/`isAncestor()` checks that are run **against another component's DOM structure or CSS class names** (e.g. matching `.action-label`, `.monaco-button`, `.action-bar`, editor/list internals). Such code silently couples one component to the private markup of another: there is no compile error or test failure when the foreign classes change, so behavior breaks at runtime in ways that are hard to trace. If you reach for `closest`/`matches` with a selector that names classes you do not own, treat it as a design smell.
111 
112Prefer, in order:
113 
1141. **Explicit, typed signals.** Have the component that owns the interaction report intent through a method call, an event, or an observable (e.g. a session view tells the part "I was activated"), instead of the part guessing from the DOM. This is the architecturally correct fix and removes the coupling entirely.
1152. **Event ownership.** Let the handler closest to the source decide — e.g. an action handler calls `stopPropagation()` / marks the event — rather than an outer delegated listener re-classifying the target after the fact.
1163. **Semantics the widget already exposes.** Use real focus (`focusin`/`trackFocus`), `tabindex`, ARIA roles, or the widget's own API instead of CSS-class sniffing.
117 
118Narrow, self-contained `contains()`/`isAncestor()` checks against an element's **own** subtree (e.g. "is this click inside the widget I created?") are acceptable — the coupling stays within a single component. The smell is reaching **across** component boundaries.
119 
120Known anti-pattern to migrate away from: `isActionableControl` in `browser/parts/sessionsPart.ts`, which uses `closest()` with a hardcoded selector of foreign action-bar/button/editor classes to decide whether a click should promote a session to active. The correct design is for the session view / chat content to signal activation explicitly (option 1 above).
121 
122## Learnings
123 
124- Always check `src/vs/sessions/LAYERS.md` before adding cross-module imports — layering violations are enforced by ESLint and will fail CI.
125- Do not classify DOM events by matching foreign components' CSS classes (`closest('.action-label')`, etc.). It couples you to markup you don't own and breaks silently. Prefer explicit activation signals, event ownership (`stopPropagation`), or real focus/ARIA semantics. See the "DOM Traversal & Intent" section.
126- When creating new views, remember to import the contribution in the entry point — missing this causes the view to not appear.
127- Session state flows through observables, not events. If you find yourself adding `onDid*` events for session state, convert to `IObservable` instead.
128