sessions

name	sessions
description	Agents window architecture — covers the agents-first app, layering, folder structure, chat widget, menus, contributions, entry points, and development guidelines. Use when implementing features or fixing issues in the Agents window.

Before Making Any Changes

MANDATORY: Before writing or modifying any code in src/vs/sessions/, you must read these documents:

1. .github/instructions/coding-guidelines.instructions.md — Naming conventions, code style, string localization, disposable management, and DI patterns.
2. .github/instructions/source-code-organization.instructions.md — Layers, target environments, dependency injection, and folder structure conventions.

Then read the relevant spec for the area you are changing (see table below). If you modify the implementation, you must update the corresponding spec to keep it in sync.

Specification Documents

Document	Path	When to read
Layer rules	src/vs/sessions/LAYERS.md	Before adding any cross-module imports. Defines the internal layer hierarchy (core → services → contrib → providers) with ESLint-enforced import restrictions. Key rule: contrib/* must NOT import from contrib/providers/*.
Layout spec	src/vs/sessions/LAYOUT.md	Before changing any part, grid structure, titlebar, or CSS. Documents the fixed grid layout (Sidebar | ChatBar | AuxiliaryBar), part positions, the modal editor system, per-session layout state persistence, and the titlebar's three-section design.
Layout controller spec	src/vs/sessions/LAYOUT_CONTROLLER.md	Before changing LayoutController or per-session layout state. Details how the auxiliary bar, panel, and editor working sets are captured/restored when switching sessions, multi-session suppression, the auto-reveal-on-changes flow, workspace-folder ordering, and storage/migration.
Sessions spec	src/vs/sessions/SESSIONS.md	Before changing session/provider interfaces or data flow. Covers the pluggable provider model (ISessionsProvider → ISessionsProvidersService → ISessionsManagementService), ISession/IChat interfaces, observable state propagation, workspace/folder model, and session type system.
Sessions list spec	src/vs/sessions/SESSIONS_LIST.md	Before changing the sessions sidebar list. Covers the tree widget (WorkbenchObjectTree), renderers, grouping (workspace/date), filtering (type/status/archived/read), pinning, read/unread state, workspace capping, mobile adaptations, storage keys, and registered actions.
Mobile spec	src/vs/sessions/MOBILE.md	Before adding any phone-specific UI. Covers the mobile part subclass architecture, viewport classification (phone < 640px), MobileTitlebarPart, drawer-based sidebar, MobilePickerSheet, view/action gating with IsPhoneLayoutContext, and the desktop → mobile component mapping.
AI Customizations	src/vs/sessions/AI_CUSTOMIZATIONS.md	Before working on the customization editor or tree view. Documents the management editor (in vs/workbench) and the tree view/overview (in vs/sessions/contrib/aiCustomizationTreeView).

Common Pitfalls

• Shared visual-module gates must not activate broader layout contracts: the Agents window may opt into shared editor-tab styles through a tab-specific root class, but must not apply the broad style-override class unless it also loads every matching Modern UI layout module. Keep shared tab runtime metrics aware of both gates, and preserve structural behavior such as a sticky add-tab action when removing a Sessions-owned stylesheet. Since the Agents workbench is always modern, chat-tab presentation belongs in the owning chatCompositeBar.css, scoped through .session-chat-tabs-bar and chat-specific classes while consuming shared state tokens; do not add Sessions selectors to or rewrite the shared editor stylesheet.

• Minimum-size activation across the Sessions/Editor split must be symmetric and layout-aware: when either part is at minimum width, pointer or keyboard activation expands it by shrinking its sibling to minimum width. In single-pane layout, the Editor grid node's effective minimum includes the visible docked Auxiliary Bar width; using editorPartView.minimumWidth alone collapses Details.

• Do not inject ISessionsService into editor-part construction: the sessions service depends on editor parts through the sessions-part graph, so injecting it into SinglePaneMainEditorPart causes recursive service instantiation during startup. Prefer lower-level services such as ILabelService when the editor only needs resource presentation.

• Workspace-folder labels must distinguish physical paths from repository identity: a worktree URI basename is the worktree directory, not the repository name. Route breadcrumb and workspace-projection labels through the delayed IWorkspaceFolderLabelService; the Agents implementation may read ISessionsService.activeSession because BreadcrumbsModel is created from BreadcrumbsControl.update() after editor-part construction, but never inject ISessionsService into SinglePaneMainEditorPart itself. Breadcrumbs omit a workspace root whenever only one folder exists in any VS Code window; folder changes rebuild the model and recompute labels.

• Session repository labels come from ISessionFolder.name, not the repository URI basename: providers may supply a richer display identity such as org/repo. Use the session folder name for plain and verbose labels, and use URI basenames only as the final no-session fallback.

Capturing Feedback (meta-rule)

Whenever the user flags a wrong pattern, rejects an approach, or gives design/rules feedback, automatically add it as a concise pitfall/learning to this Common Pitfalls section (or the most relevant spec doc) in the same change — without being asked again. Keep each entry 1–3 sentences: the anti-pattern, why it is wrong, and the preferred pattern.

• Menu-order changes must update every registration assertion: action ordering can be covered by tests outside the action's owning contribution. Search for the previous order and command id, then update all affected expectations so focused tests do not leave the broader suite stale.

• Shared commands must delegate behavior to the layout service, not inspect a layout implementation: workbench.action.toggleAuxiliaryBar must call the semantic IWorkbenchLayoutService.toggleSecondarySideBar() operation. Do not branch on optional layout properties or concrete workbench shape in the shared action; each workbench owns how its secondary-sidebar affordance maps to visible parts.

• Definitive session deletion and temporary list eviction are different operations: deletion clears durable provenance and pending state; filtering a still-existing session only removes its visible list entry. Keep the list-removal helper side-effect-free, and let each caller explicitly update its mutation generation instead of passing an "already incremented" boolean.

• Durable user intent must never be discarded on onDidChangeSessions.removed: pins, manual sort keys, and group membership (SessionsListModelService, SessionGroupsService) are cleared only on ISessionsManagementService.onDidDeleteSession (or archive), never on the provider's removed delta. removed is an eviction, not a deletion: BaseAgentHostSessionsProvider._refreshSessions reconciles against one listing that the host aggregates across all its agents, and an agent that cannot answer yet returns [] instead of failing (CodexAgent.listSessions returns [] for a missing _githubToken, a not-yet-downloaded SDK, or a failed thread/list; ClaudeAgent.listSessions does the same). Persisting the removal turned a ~300 ms startup race into permanent loss of the user's pins and groups. Runtime-only consumers of removed (terminals, grid slots, layout) are fine as-is — only persisted state needs the delete event.

• _refreshSessions must not evict a cached session whose agent contributed no rows: a listing with zero rows for an agent means "unknown", not "empty", so scope eviction to listedAgentProviders (the set of AgentSession.provider(...) schemes actually present in the response) and compare against . Real deletions still arrive through and the notification; the only cost is that an agent's session, deleted elsewhere, lingers until it lists something again.