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