Move the /troubleshoot built-in skill into the agent host

[vijayupadya]

Summary

Reimplements the /troubleshoot built-in skill and its #session reference support in the agent host, so it works identically across the VS Code chat editor, the Agents window, and standalone/remote hosts — instead of being wired per-client in the sessions layer. The plumbing is generic, so any future built-in skill gets loading, autocomplete, and invocation for free.

What it does

• /troubleshoot loads a bundled skill that analyzes a Copilot CLI session's on-disk event log to explain unexpected behavior.
• #session:<title> references another session so /troubleshoot analyzes that session's log instead of the current one. Follow-ups in the same chat can use a bare /troubleshoot and stay on the referenced session (sticky).

How it works

• Built-in skill manifest (copilotBuiltinSkills.ts): a single BUILTIN_SKILLS list drives everything — the folder is fed to the SDK's skillDirectories, surfaced in / completions, and dispatched deterministically.
• Invocation (agentHostSkillInvocation.ts): a / built-in skill is rewritten into the canonical Use the skill tool to invoke the '' skill… message so it runs reliably.
• Troubleshoot log targeting (agentHostTroubleshoot.ts): resolves #session markers to the harness's on-disk log path (host-local, so it works remotely); bare requests defer to the skill's sticky/self-discovery rules.
• Harness-driven completions (agentHostSessionReferenceCompletionProvider.ts, copilotSlashCommandCompletionProvider.ts): /troubleshoot shows in autocomplete even before a session materializes; #session completions come from the host (newest-first, dated, file matches suppressed) with a short-TTL cache to avoid per-keystroke session listing.

Architecture

---

1. Where it lives (layers)

   CLIENTS (thin: just render & forward)
   +-----------------------+     +-----------------------+
   |     Chat editor       |     |    Agents window      |
   |   (workbench chat)     |     |    (vs/sessions)      |
   +-----------+-----------+     +-----------+-----------+
               |                             |
               +--------------+--------------+
                              |  (completions + send over AHP)
   ===========================|=================================
   AGENT HOST (shared backend)|
                              v
   common/  (harness-agnostic)
   +-----------------------------------------------------------+
   |  agentHostSkillInvocation.ts   buildSkillInvocationPrompt |
   |  agentHostTroubleshoot.ts      augmentTroubleshootRequest |
   |  meta/agentSessionReferenceMeta.ts     (#session _meta)   |
   |  meta/agentCompletionAttachmentMeta.ts (completion _meta) |
   +-----------------------------------------------------------+
                              ^
   node/copilot/ (Copilot CLI harness)                    |
   +-----------------------------------------------------------+
   |                 copilotBuiltinSkills.ts                   |
   |                   [ BUILTIN_SKILLS ]  <== single source    |
   |             skills/troubleshoot/SKILL.md (bundled)         |
   |                                                           |
   |   copilotSessionLauncher.ts .............. skillDirectories|
   |   copilotSlashCommandCompletionProvider .. "/" completions |
   |   agentHostSessionReferenceCompletionProvider . #session   |
   |   copilotAgentSession.send() ............. dispatch        |
   +-----------------------------+-----------------------------+
                                 |
                                 v
                    +-------------------------+
                    |   @github/copilot-sdk   |
                    | CLI runtime + skill tool|
                    +-------------------------+

The BUILTIN_SKILLS manifest is the single source of truth. It drives three
independent paths: loading, autocomplete, and dispatch.

---

2. Three things the manifest drives

                         BUILTIN_SKILLS
                       { name, description }
                               |
        +----------------------+----------------------+
        |                      |                      |
        v                      v                      v
  getBuiltinSkill        getBuiltinSkills        isBuiltinSkill
   Directories                 |                      |
        |                      |                      |
        v                      v                      v
  LOADING               AUTOCOMPLETE             DISPATCH
  SDK skillDirectories  "/name" shows in         send() rewrites "/name"
  -> runtime loads      completions (even        into a deterministic
  the SKILL.md          pre-materialization)     skill invocation

Adding a new built-in skill = create skills/<name>/SKILL.md + one manifest entry.
Loading, autocomplete, and deterministic invocation come for free.

---

3. Autocomplete flow (/troubleshoot and #session)

User types "/tr..."                         User types "#session:"
      |                                            |
      v                                            v
  Client --- completions(channel,text) --->  Agent host (fan-out)
      |                                            |
      |  "/troubleshoot"                           |  AgentHostSessionReference
      |  (from BUILTIN_SKILLS manifest)            |  CompletionProvider:
      |                                            |   - listSessions() [short-TTL cache]
      |                                            |   - file matches suppressed for #session
      |                                            |   - one item / other session,
      v                                            |     newest-first, dated
  shows /troubleshoot  <----- items --------- <----+
  (before session materializes)              shows #session:<title> list

• / completions come from the manifest, so /troubleshoot appears before the
  session materializes.
• #session completions come from the host's session list (cached to avoid
  per-keystroke listing) and render as attachment "pills" client-side.
• #-token results are marked incomplete so the host re-queries as you type.

---

4. Dispatch flow (what makes the skill actually run)

A skill loaded via skillDirectories is only available — the runtime does not reliably
run it from a bare /name. The host rewrites the message into a deterministic skill
invocation.

Client sends: "/troubleshoot #session:X"  (+ attachment: #session -> X)
      |
      v
copilotAgentSession.send()
      |  isBuiltinSkill("troubleshoot")? --- yes
      v
augmentTroubleshootRequest(userText, attachments, resolveLogPath)
      |  - resolve #session marker -> X's on-disk log path
      |  - drop the marker (not forwarded)
      |  - pin "Session log: <X path>"
      v
rewritten prompt:
   "Use the skill tool to invoke the 'troubleshoot' skill,
    then follow the skill's instructions.

    Session log: <X path>"
      |
      v
session.send(prompt)  ->  CLI runtime  ->  skill tool (SKILL.md injected)
                                              |
                                              v
                                    reads X's events.jsonl, analyzes
                                              |
                                              v
                                     troubleshooting result -> client

Reference vs. bare / sticky follow-ups

                 /troubleshoot request
                          |
                #session reference?
                  /               \
               yes                 no
                |                   |
  pin "Session log:          inject NO path
   <referenced log>"                |
  drop marker,              skill's own rules:
  ignore its title           - sticky: continue the session
                               established earlier in the chat
                             - else: self-discover current session
                  \               /
                   v             v
             skill invocation message -> SDK

• /troubleshoot #session:X -> analyzes X.
• A later bare /troubleshoot follow-up in the same chat -> stays on X (skill's
  sticky rule); no need to re-attach.
• Generic (non-troubleshoot) built-in skills skip the log logic and use
  buildSkillInvocationPrompt(name, userText) directly.

---

[Copilot]

Pull request overview

Moves /troubleshoot and #session handling into the agent host for consistent local, remote, standalone, and Agents window behavior.

Changes:

• Adds bundled skill discovery and deterministic invocation.
• Adds host-driven session-reference completions and log targeting.
• Removes client-specific troubleshooting plumbing and adds tests.

Show a summary per file

File	Description
src/vs/workbench/contrib/chat/common/chatSessionsService.ts	Adds session-reference completion attachments.
src/vs/workbench/contrib/chat/common/attachments/chatVariableEntries.ts	Represents host session references.
src/vs/workbench/contrib/chat/browser/widget/input/editor/chatInputCompletionUtils.ts	Returns the active trigger character.
src/vs/workbench/contrib/chat/browser/widget/input/editor/agentHostInputCompletionsBase.ts	Refreshes hash completions while typing.
src/vs/workbench/contrib/chat/browser/widget/input/editor/agentHostInputCompletions.ts	Renders and accepts session references.
src/vs/workbench/contrib/chat/browser/agentSessions/agentHost/agentHostSessionHandler.ts	Bridges session references to AHP attachments.
src/vs/sessions/services/sessions/browser/sessionsManagementService.ts	Removes client-side troubleshooting rewriting.
src/vs/sessions/services/sessions/browser/sessionReference.ts	Removes obsolete reference helpers.
src/vs/sessions/contrib/chat/browser/sessionReferenceCompletions.ts	Removes client-owned completions.
src/vs/sessions/contrib/chat/browser/newChatInput.ts	Removes the legacy provider registration.
src/vs/sessions/contrib/chat/browser/agentHostInputCompletions.ts	Handles host-provided session references.
src/vs/platform/agentHost/test/node/copilotSlashCommandCompletionProvider.test.ts	Tests built-in slash completions.
src/vs/platform/agentHost/test/node/copilotBuiltinSkills.test.ts	Tests built-in skill registration.
src/vs/platform/agentHost/test/node/agentHostSessionReferenceCompletionProvider.test.ts	Tests session completion and caching.
src/vs/platform/agentHost/test/common/agentHostTroubleshoot.test.ts	Tests troubleshooting request rewriting.
src/vs/platform/agentHost/test/common/agentHostSkillInvocation.test.ts	Tests canonical skill prompts.
src/vs/platform/agentHost/node/copilot/skills/troubleshoot/SKILL.md	Defines the bundled troubleshooting workflow.
src/vs/platform/agentHost/node/copilot/copilotSlashCommandCompletionProvider.ts	Surfaces built-in skills in completions.
src/vs/platform/agentHost/node/copilot/copilotSessionLauncher.ts	Loads bundled skill directories.
src/vs/platform/agentHost/node/copilot/copilotBuiltinSkills.ts	Declares the built-in skill manifest.
src/vs/platform/agentHost/node/copilot/copilotAgentSession.ts	Dispatches skills and resolves log paths.
src/vs/platform/agentHost/node/copilot/copilotAgent.ts	Registers built-ins and session completions.
src/vs/platform/agentHost/node/agentHostSessionReferenceCompletionProvider.ts	Provides cached session completions.
src/vs/platform/agentHost/node/agentHostFileCompletionProvider.ts	Suppresses conflicting file matches.
src/vs/platform/agentHost/common/meta/agentSessionReferenceMeta.ts	Defines session-reference metadata.
src/vs/platform/agentHost/common/meta/agentCompletionAttachmentMeta.ts	Classifies session completion metadata.
src/vs/platform/agentHost/common/agentHostTroubleshoot.ts	Rewrites troubleshooting requests.
src/vs/platform/agentHost/common/agentHostSkillInvocation.ts	Builds deterministic skill prompts.

Review details

Comments suppressed due to low confidence (1)

src/vs/platform/agentHost/node/agentHostSessionReferenceCompletionProvider.ts:122

• Untitled session is displayed directly in completion UI but bypasses localization. Host-provided completion descriptions already use localize (for example copilotBuiltinSkills.ts:46), and the removed client implementation localized this same fallback. Localize this label so non-English builds do not regress.

		const title = (session.summary ?? '').replace(/\s+/g, ' ').trim() || 'Untitled session';

• Files reviewed: 27/28 changed files
• Comments generated: 5
• Review effort level: Medium