sessions

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: sessions
description: Core principles and workflow router for changes to the Agents Window under src/vs/sessions.
---

# Agents Window development

Use this skill for implementation, review, or design work under `src/vs/sessions/**`.

## 1. Apply the core principles

- Preserve the layer direction: `vs/sessions` may import `vs/workbench` and lower layers; `vs/workbench` must never import `vs/sessions`.
- Keep shared Sessions code provider-neutral. Non-provider contributions must not import provider implementations.
- Model mutable session and chat state with observables. Use events for notifications, not as a parallel state model or for control flow.
- Register Sessions menu IDs in `browser/menus.ts` and consume `Menus.*`.
- Import contributions from the appropriate `sessions.*.main.ts` entry point.
- Prefer Sessions-owned adaptations over shared workbench changes unless the capability is genuinely shared.
- Put stable architecture in the owning specification and concrete behavior in tests. Do not preserve implementation chronology as development guidance.

## 2. Identify the owning area

Start with `src/vs/sessions/README.md`, then read only the specifications relevant to the change:

| Area | Specification |
|------|---------------|
| Layering, folder ownership, cross-module imports | `src/vs/sessions/LAYERS.md` |
| Session/chat model, services, provider contract, core data flow | `src/vs/sessions/SESSIONS.md` |
| Automations ownership, routing, migration, persistence, and run lifecycle | `src/vs/sessions/AUTOMATIONS.md` |
| Workbench parts, grid, title bar, editor presentation | `src/vs/sessions/LAYOUT.md` |
| Session-aware layout state and restoration | `src/vs/sessions/LAYOUT_CONTROLLER.md` |
| Single-pane behavior and expected compositions | `src/vs/sessions/SINGLE_PANE_SCENARIOS.md` |
| Sessions sidebar list, grouping, filtering, and persistence | `src/vs/sessions/SESSIONS_LIST.md` |
| Phone layout and mobile components | `src/vs/sessions/MOBILE.md` |
| AI customizations | `src/vs/sessions/AI_CUSTOMIZATIONS.md` |
| Copilot customizations | `src/vs/sessions/copilot-customizations-spec.md` |
| Copilot Chat provider | `src/vs/sessions/contrib/providers/copilotChatSessions/COPILOT_CHAT_SESSIONS_PROVIDER.md` |
| Agent Host provider | `src/vs/sessions/contrib/providers/agentHost/AGENT_HOST_SESSIONS_PROVIDER.md` |
| Remote Agent Host provider | `src/vs/sessions/contrib/providers/remoteAgentHost/REMOTE_AGENT_HOST_SESSIONS_PROVIDER.md` |

Do not load the learning inbox by default. Search its headings and scopes, then read only matching entries after the authoritative specification.

## 3. Inspect before changing

- Trace the current implementation and its existing tests.
- Search for shared helpers, context keys, menu IDs, entry-point imports, and provider abstractions before adding new ones.
- Confirm which layer owns the behavior. Keep provider-specific decisions in the provider and view/layout decisions in Sessions-owned browser code.
- For UI work, also invoke the applicable accessibility, design, CSS, layout, or theming skill.
- For agent, LLM, policy, permissions, telemetry, or managed-setting changes, invoke the applicable specialist skill before implementation.

## 4. Implement the contract

Apply the core principles and the focused specification. Prefer small changes that preserve these boundaries:

- `ISessionsManagementService` owns model orchestration and provider routing.
- `ISessionsService` owns visible and active session behavior.
- Providers expose provider-neutral state through `ISession` and `IChat`.
- Session state is observable; consumers derive UI state reactively.
- Contributions load through the appropriate `sessions.*.main.ts` entry point.
- Sessions menus use the shared `Menus` registry.
- Shared workbench changes represent shared capability, not Sessions-specific policy.

### Specification edit gate

Bug fixes do not update specifications when they restore an existing contract. Before editing