Microsoft 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/sessionsmay importvs/workbenchand lower layers;vs/workbenchmust never importvs/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.tsand consumeMenus.*. - Import contributions from the appropriate
sessions.*.main.tsentry 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:
ISessionsManagementServiceowns model orchestration and provider routing.ISessionsServiceowns visible and active session behavior.- Providers expose provider-neutral state through
ISessionandIChat. - Session state is observable; consumers derive UI state reactively.
- Contributions load through the appropriate
sessions.*.main.tsentry point. - Sessions menus use the shared
Menusregistry. - 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:
- the existing ownership, interface, lifecycle, state-machine, persistence, or cross-component contract that intentionally changes;
- the implementation surfaces affected by that contract change;
- 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-checkwhen 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.