Add Aspire editor assistance language model tools

[Adam Ratzman (adamint)]

Description

Copilot can start and stop an Aspire AppHost, but it could not safely answer the editor-owned
questions that usually come next: is this AppHost already debugging, which Aspire sessions are
active, where is the Dashboard, what happened during the last failed launch, and how do I get the
Aspire Output view in front of the user?

This adds five narrow VS Code language-model tools:

Tool	Input	Confirmation	Safe success result
aspire_debug_session_status	Workspace-relative AppHost path and optional exact resource name	No	Bounded AppHost/resource state, controller, mode, and safe display path
aspire_list_debug_sessions	Empty object	No	At most 20 editor-owned AppHost summaries, plus a truncated marker when needed
aspire_open_dashboard	Workspace-relative AppHost path	Yes	opened and one bounded presentation bucket
aspire_open_output	Empty object	Yes	opened
aspire_explain_launch_failure	Workspace-relative AppHost path	No	The latest unexpired sanitized failure and bounded recommended action identifiers

These are editor-assistance tools, not lifecycle or diagnostic tools. They do not start, stop, or
restart AppHosts/resources, scrape terminal output, summarize logs, return Dashboard URLs, or add a
second MCP implementation.

One editor-assistance subsystem

The tools are thin adapters over four shared services:

• SafeAppHostTargetResolver resolves only AppHosts already discovered through the Aspire
  workspace registry. It supports multi-root workspaces, returns absolute paths only inside the
  extension, and exposes workspace-relative display paths to tool results and confirmation copy.
• EditorStateSnapshotService projects editor-owned Aspire run/debug sessions into bounded AppHost
  and resource summaries. Full, active-only, and exact-AppHost queries now share one projection
  pipeline.
• EditorUiHandoffService uses the existing Dashboard launcher/browser policy and Aspire Output
  channel. It does not duplicate browser selection, Dashboard ownership, or CLI resource-state logic.
• LaunchFailureJournal stores only normalized launch-failure categories in memory for the lifetime
  of the extension window.

Aspire CLI remains the control plane for AppHost/resource discovery and running-state refresh.

Trust, identity, and confirmation

Language-model input is treated as untrusted.

• Every contribution has when: "isWorkspaceTrusted".
• Every invocation checks workspace trust again.
• Schemas and runtime validators reject additional properties.
• AppHost selectors are matched against discovered candidates instead of being joined to the
  filesystem.
• Multi-root selectors must use the stable folder-qualified display path.
• Missing, ambiguous, outside-workspace, changed, or stale targets fail closed.
• Confirmed and launched targets are bound to an opaque canonical-target identity. Symlink
  retargeting changes identity, while an atomic save or checkout of the same AppHost does not.
• Dashboard confirmation shows the safe display path, then the target is resolved again after the
  user accepts. A model cannot confirm one AppHost and swap the selector before the UI operation.
• Dashboard preparations are one-shot, time-bounded, and capped at 32 outstanding selectors. The
  stable VS Code API does not expose its internal prepare/invoke correlation identifier, so
  overlapping, expired, or overflowed preparation state switches the tool to a conservative
  invocation-time confirmation mode for the rest of the extension window. That mode freshly
  resolves the target, shows one localized modal confirmation, and re-resolves again before opening.
  This preserves the handoff without allowing a delayed invocation to consume another call's
  confirmed target.
• Dashboard ownership requires exactly one editor session whose captured AppHost identity and CLI
  PID both match the fresh repository row. Ownerless external CLI rows fail closed because they do
  not carry a launch-time identity that remains trustworthy after symlink retargeting or file
  replacement.
• Output uses the existing Aspire Output channel with show(true), so the Output view opens without
  stealing focus from the active editor.

The final lifecycle review also tightened three adjacent ownership boundaries:

• disposed debug sessions no longer remain eligible as Dashboard owners;
• failed initial resource snapshots cancel and observe the already-started CLI watch without
  replacing the original failure or reporting expected cancellation as an independent watch error;
• editor assistance now uses the canonical current-target identity API instead of maintaining a
  second lexical identity registry.

Bounded session results

aspire_debug_session_status returns only:

• running
• starting
• stopping
• notDebugging
• multipleSessions
• bounded missing/ambiguous/trust/input/cancellation/error outcomes

With resourceName, lookup is scoped to the exact resolved AppHost and refreshed through CLI-backed
resource state. Missing or duplicate exact names fail closed. The result does not include the
resource snapshot or resource properties. The caller-supplied exact resource name is echoed only to
identify the requested scope; it is never included in telemetry.

aspire_list_debug_sessions reports only editor-owned active AppHost summaries. Each item contains
the safe AppHost display path plus bounded state, controller, and mode values. Results are
sorted, capped at 20, and marked truncated when more active AppHosts exist.

Launch-failure journal

Launch failures are captured where they occur during discovery, validation, CLI launch, build, DCP
startup, debug-session startup, and Dashboard opening. The original error is normalized immediately
and discarded.

Each record contains only:

• stage
• category
• controller
• mode
• provider kind
• exit-code bucket
• opaque in-memory AppHost identity
• timestamp and sequence used for journal maintenance

The journal is memory-only, keeps at most five failures per AppHost and 50 globally, and expires
records after approximately 30 minutes. Launch-attempt fallback suppression is correlated to the
exact internal launch token so one launch cannot hide another launch's failure.

aspire_explain_launch_failure maps the latest unexpired record to bounded action identifiers such
as fixBuildErrors, installAspireCli, freeRequiredPort, or retryLaunch. It does not manufacture
detailed guidance when the normalized category is unknown.

Privacy boundary

Tool results, telemetry, journal records, and persisted E2E evidence do not contain:

• absolute paths
• PIDs or VS Code/debug session IDs
• Dashboard/resource URLs
• command-line arguments
• environment values
• resource properties
• debug configurations
• raw exception messages or stack traces
• stdout, stderr, logs, or build output
• tokens, connection strings, or credentials

The packaged Extension Host tests recursively inspect the persisted editor-assistance artifact for
these values rather than checking only individual result fields.

Telemetry

Two typed events were added:

• aspire/vscode/editorassistance/result
• aspire/vscode/launchfailure/recorded

They accept only bounded dimensions:

• tool/outcome/source/scope
• controller/mode/state bucket
• stage/category/provider kind/exit-code bucket
• presentation/error kind
• duration and current journal size

AppHost paths, resource names, caller-supplied extension IDs, URLs, and raw errors are not accepted.
Tests inspect the exact telemetry payloads and classifications in telemetry.json.

Edge-case coverage

Scenario	Unit	Packaged Extension Host
Strict schemas/additional-property rejection	✅	✅
Multi-root and ambiguous AppHost selectors	✅
Symlink retargeting, atomic replacement, and stale-session identity	✅	Focused Extension Host
Workspace trust rejection	✅	Manifest/package surface
AppHost status before, during, and after debug	✅	✅
Exact resource status and missing/duplicate resources	✅	✅ where fixture-backed
Multiple editor sessions	✅
Session-list sorting, 20-item cap, and truncation	✅	Bounded real result
Dashboard unavailable/stopped AppHost	✅	✅
Dashboard browser-presentation buckets	✅	✅
Dashboard/Output accepted confirmation	✅	✅
Dashboard/Output denied confirmation	✅	✅
Abandoned, overlapping, expired, and overflowed Dashboard preparation	✅	✅ denial/retry path
Post-confirmation AppHost re-resolution	✅
No recorded failure/latest bounded failure	✅	✅
Journal TTL/per-AppHost/global capacity	✅
Failure capture at every integrated boundary	✅
Cleanup disconnect(false) does not hide startup failure	✅
Telemetry and result privacy	✅	✅

The scenarios that need a synthetic clock, more than 20 concurrent sessions, duplicate internal
resource snapshots, or symlink retargeting stay in focused unit tests. The user-facing paths run
through a packaged VSIX in a real VS Code Extension Host and call vscode.lm.invokeTool.

Screenshots / recordings

Dashboard confirmation:

Output confirmation:

These are real VS Code confirmation dialogs captured during the packaged Extension Host run. There
is no meaningful "before" screenshot because the change adds language-model tool entry points rather
than changing an existing visible view.

Validation

Final head: 7e5a676d0d6e3a65e4b55c6c536da7d6599e8d07

• yarn compile-tests, yarn compile, and yarn lint
• Extension Host suite — 2,223 passing, 4 pending
• Dashboard preparation/fallback lifecycle focus — 9/9 passing
• Table-format follow regression — 20 consecutive focused runs passing
• Aspire CLI DescribeCommandTests — 39/39 passing
• Packaged VSIX Extension Host lifecycle/editor-assistance E2E — 2/2 passing
• Packaged VSIX package-surface E2E — 7/7 passing
• Packaged VSIX tree-actions E2E — 1/1 passing
• Required GitHub checks — running on the final head
• Copilot review — no unresolved review threads after the final push

The tree-actions failure on an earlier head exposed a CLI follow-mode bug: the
includeDisabledCommands value was passed positionally as the environment-value flag. The call now
uses the named argument, preserving environment-value behavior and including disabled commands in
the streamed snapshot. The command-level regression test and packaged tree-actions scenario both
cover this path.

The final packaged lifecycle run also caught an E2E-only preparation leak: the bridge inspected
prepareInvocation output without canceling that synthetic preparation. The bridge now cancels and
disposes its token in finally, matching the fact that the inspection never invokes the tool and
preventing it from affecting the next real packaged invocation.

No dependency versions, lockfiles, or MCP contributions changed.

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19414

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19414"

[Copilot]

Pull request overview

Adds five privacy-bounded VS Code language-model tools for inspecting Aspire debug state, explaining launch failures, and opening relevant UI.

Changes:

• Adds editor-state snapshots, safe AppHost resolution, failure journaling, and telemetry.
• Adds confirmation-gated Dashboard and Output handoffs.
• Extends debugger metadata and comprehensive unit/E2E coverage.

Show a summary per file

File	Description
extension/telemetry.json	Defines new telemetry events.
extension/src/views/AspireAppHostTreeProvider.ts	Reuses Dashboard URL validation.
extension/src/utils/telemetryRegistry.ts	Types new telemetry schemas.
extension/src/utils/appHostIdentity.ts	Adds opaque lexical identities.
extension/src/types/extensionApi.ts	Extends E2E invocation controls.
extension/src/testing/e2eStateFileBridge.ts	Supports testing all LM tools.
extension/src/testing/e2eStateFileBridge.production.ts	Updates production bridge signature.
extension/src/test/telemetryInventory.test.ts	Adjusts telemetry inventory test.
extension/src/test/strings.test.ts	Verifies localized confirmations.
extension/src/test/rustDebugger.test.ts	Tests typed Rust build failures.
extension/src/test/launchFailureTelemetry.test.ts	Tests sanitized failure telemetry.
extension/src/test/dotnetDebugger.test.ts	Tests typed .NET build failures.
extension/src/test/dcpTypes.test.ts	Tests safe launch-path extraction.
extension/src/test/AspireExtensionContext.test.ts	Tests assistance-state lifecycle.
extension/src/test/aspireDebugConfigurationProvider.test.ts	Tests discovery-failure journaling.
extension/src/test/appHostLifecycleTools.test.ts	Updates lifecycle-tool coverage.
extension/src/test/appHostDataRepository.test.ts	Tests one-shot resource queries.
extension/src/test/adapterTracker.test.ts	Tests AppHost termination attribution.
extension/src/test-e2e/packageSurface.e2e.test.ts	Verifies packaged tool contributions.
extension/src/test-e2e/appHostLifecycleTools.e2e.test.ts	Exercises assistance tools end-to-end.
extension/src/services/launchFailureJournal.ts	Implements bounded failure journal.
extension/src/services/editorAssistanceWindowState.ts	Resets activation-scoped state.
extension/src/services/AppHostLaunchService.ts	Exposes safe session state and journaling.
extension/src/services/appHostLaunchReservations.ts	Reports pending external runs.
extension/src/services/appHostLaunchContracts.ts	Defines safe session snapshots.
extension/src/server/interactionService.ts	Reuses Dashboard-launch helpers.
extension/src/loc/strings.ts	Adds localized confirmation strings.
extension/src/lm/safeAppHostTargetResolver.ts	Resolves trusted workspace AppHosts.
extension/src/lm/languageModelToolUi.ts	Escapes confirmation Markdown.
extension/src/lm/editorUiHandoffService.ts	Handles Dashboard and Output UI.
extension/src/lm/editorStateSnapshotService.ts	Produces bounded session summaries.
extension/src/lm/editorAssistanceToolContracts.ts	Defines tool contracts and validation.
extension/src/lm/editorAssistanceToolAdapters.ts	Registers the five tools.
extension/src/lm/editorAssistanceTelemetry.ts	Emits bounded result telemetry.
extension/src/lm/appHostLifecycleToolService.ts	Shares safe target resolution.
extension/src/lm/appHostLifecycleTools.ts	Updates lifecycle exports.
extension/src/lm/appHostLifecycleToolContracts.ts	Extends lifecycle service contracts.
extension/src/lm/appHostLifecycleToolAdapters.ts	Shares UI escaping and E2E access.
extension/src/extension.ts	Wires editor-assistance services.
extension/src/debugger/languages/rust.ts	Uses typed build failures.
extension/src/debugger/languages/dotnet.ts	Uses typed build failures.
extension/src/debugger/debuggerExtensions.ts	Captures structured resource identity.
extension/src/debugger/AspireDebugConfigurationProviderInternal.ts	Tracks recorded discovery failures.
extension/src/debugger/AspireDebugConfigurationProvider.ts	Journals terminal launch failures.
extension/src/debugger/appHostBuildFailureError.ts	Defines build-failure boundary type.
extension/src/debugger/adapterTracker.ts	Tracks explicit AppHost termination.
extension/src/dcp/types.ts	Extracts safe target/executable paths.
extension/src/data/AppHostDataRepository.ts	Exposes cancellable resource snapshots.
extension/src/AspireExtensionContext.ts	Exposes safe editor session projections.
extension/package.nls.json	Adds localized manifest strings.
extension/package.json	Contributes and activates new tools.
extension/loc/xlf/aspire-vscode.xlf	Updates localization catalog.

Review details

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 58/59 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

extension/src/lm/editorUiHandoffService.ts:121

• This reports opened even when the notification was not shown. showDashboardLaunchNotification catches a synchronous showInformationMessage failure (and asynchronous rejection), logs it, and returns void, so this tool cannot distinguish that failure from a successful presentation. Have the shared helper return/await a success result and return the bounded error outcome when presentation fails.

            if (resolvedBehavior.behavior === 'notification') {
                showDashboardLaunchNotification({
                    baseUrl: dashboardUrl,
                    source: resolvedBehavior.source,
                });
                return { outcome: 'opened', presentation: 'notification' };

• Files reviewed: 70/71 changed files
• Comments generated: 1
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Adam Ratzman (adamint)]

Copilot review

[Copilot]

Review details

• Files reviewed: 70/71 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 70/71 changed files
• Comments generated: 2
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

Suppressed comments (3)

Previously missed (3) — in code that hasn't changed since the last review.

extension/src/data/AppHostDataRepository.ts:632

• This cache lookup is not bound to the AppHost identity that created the describe stream. If a stream was opened through a symlink and that symlink is retargeted, both strings now resolve through the new target, so this returns the old AppHost's cached resources. A resource-scoped status request can then report notDebugging for a resource that does not exist in the newly resolved AppHost instead of failing closed. Capture the opaque target identity when the describe stream is created and require that identity to match here.

    private _getAppHostResources(appHostPath: string): ResourceJson[] {
        const matchingStreams = Array.from(this._describeStreams.entries())
            .filter(([currentAppHostPath]) => compareAppHostIdentity(currentAppHostPath, appHostPath) === 'same');
        return matchingStreams.length === 1
            ? Array.from(matchingStreams[0][1].resources.values())
            : [];

extension/src/services/AppHostLaunchService.ts:557

• Pending and active run state is correlated by re-resolving stored paths at query time. If an AppHost was launched through a symlink and the symlink is retargeted before the session snapshot is available, the stored path and the newly selected target both resolve to the new file, so the status tool reports the new AppHost as starting even though the launch belongs to the old target. Store the opaque identity with each pending/active launch and compare identities here.
  extension/src/services/appHostLaunchReservations.ts:101
• This is not a launch-time identity match: compareAppHostIdentity resolves the reservation path again. After a symlink-backed external reservation is created, retargeting that symlink makes the reservation appear to belong to the new AppHost, so editor assistance incorrectly reports that new target as starting. Capture the opaque target identity in the reservation and compare it with the current target identity instead.

• Files reviewed: 70/71 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

• Files reviewed: 70/71 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

extension/src/lm/editorAssistanceToolAdapters.ts:188

• In invocation-time confirmation mode, a rejected showWarningMessage promise escapes from the tool instead of producing the bounded error/canceled result promised by this surface. This mode is used after overlapping, expired, or overflowed preparations, so an Extension Host/UI failure can make vscode.lm.invokeTool reject and expose an uncontrolled error rather than the tool contract. Catch the modal failure and return a bounded outcome (using canceled when the token was canceled).

        const selected = await vscode.window.showWarningMessage(
            editorAssistanceOpenDashboardConfirmationTitle,
            {
                modal: true,
                detail: editorAssistanceOpenDashboardConfirmationMessage(preparedTarget.displayPath),
            },
            confirmationItem);

• Files reviewed: 70/71 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.