sessions

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

# 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` |
| 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 an authoritative specification, identify all three:

1. the existing ownership, interface, lifecycle, state-machine, persistence, or
   cross-component contract that intentionally changes;
2. the implementation surfaces affected by that contract change;
3. why a regression test and a brief code comment cannot fully represent it.

If any answer is missing, leave the specification unchanged. Put concrete
behavior in a focused test, keep a non-obvious implementation constraint beside
the owning code, and preserve investigation history in the issue or pull
request.

Update a specification only when component ownership, an interface or lifecycle
contract, a state machine, persistence, or a cross-component invariant changes.
Do not update specifications for styling, copy, action placement, telemetry
fields, settings defaults, implementation algorithms, or individual bug fixes.
Those details belong in code and focused tests.

## 5. Validate proportionally

Run the smallest existing checks that cover the change:

- focused unit tests for affected behavior;
- `npm run valid-layers-check` when imports or module ownership change;
- targeted type checking or compilation when TypeScript changes warrant it;
- relevant integration, E2E, or visual validation for cross-process or UI work.

Documentation-only changes require link, path, and consistency checks rather
than a full build.

## 6. Record feedback correctly

When a user explicitly corrects or rejects an approach, invoke the
`feedback-learning` skill unless they use the literal `learn!` trigger. Literal
`learn!` requests follow `.github/instructions/learnings.instructions.md`
instead. A durable architecture invariant belongs in the owning specification,
concrete behavior belongs in a regression test, and unproven reusable guidance
belongs temporarily in the scoped learning inbox. Never append every correction
to this skill.

## 7. Maintain this skill

Update this skill only when a principle is stable, cross-cutting, and useful for
most Agents Window work, or when the routing/workflow itself changes. Put
subsystem contracts in their focused specification and bug behavior in tests.

Keep the core-principles section at no more than ten bullets. Before adding one,
merge overlap, remove obsolete guidance, and prefer rewriting an existing
principle. Never append incident-specific details or use this skill as a
learning log.