sessions

Summary

---
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` |
| 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.

Security audits