sessions

Internal engineering guidance for working on the Agents window in the VS Code source tree, specifically the code under src/vs/sessions/. It describes an agents-first application built by layering on top of the workbench, and it is meant to be loaded before implementing features or fixing issues in that window so changes follow the established architecture.

Before any code change it requires reading the repository coding-guidelines and source-code-organization instruction files, then the specific specification document for the area being touched. Those specs are enumerated in a table and cover the internal layer hierarchy (core, services, contrib, providers with ESLint-enforced import restrictions), the fixed grid layout and titlebar, the per-session layout controller, the pluggable sessions and provider model, the sessions sidebar list, the mobile part architecture, and the AI customizations editor. Any implementation change must be mirrored back into the matching spec to keep them in sync.

A large portion of the document is a catalog of common pitfalls drawn from real mistakes: using the wrong menu identifiers, using events where observables are required, importing from provider-only modules, forgetting to register new contributions in the correct entry point, and modifying shared workbench code instead of extending it. It is emphatic that timeouts and arbitrary delays must never be used to paper over ordering or state problems, that provider-internal services must stay isolated to their provider, and that comments should be kept minimal. Use it as the authoritative checklist when contributing to the Agents window.