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 and bounded by outstanding confirmations. Consumed state is
  retired, overlapping or unresolved preparations retain fail-closed invocation slots, and
  exceeding the concurrent preparation limit disables the handoff for that extension activation.
• 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.

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.

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	✅	✅
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: 46dad7cec0cf9991f52ac9048164d4a745d30ed1

• yarn compile-tests, yarn compile, and yarn lint
• Extension Host suite — 2,213 passing, 4 pending
• Ownerless/editor-owned Dashboard handoff focus — 38/38 passing
• Table-format follow regression — 20 consecutive focused runs passing
• Aspire CLI DescribeCommandTests — 34/34 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 — 364 successful and 3 skipped on the final head
• Copilot review — completed on the final head with no unresolved review threads

The tree-actions failure on the previous 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.

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

[Adam Ratzman (adamint)]

Copilot review

[Copilot]

Review details

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

[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

Suppressed comments (1)

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

extension/src/data/AppHostDataRepository.ts:632

• These describe streams are keyed only by their lexical launch path, but compareAppHostIdentity re-resolves that path against the current filesystem. If a symlink used to launch AppHost A is retargeted to AppHost B, the still-running A stream now compares as B and its cached resources are returned to B's status request. This can affirm a resource that does not exist in the selected AppHost. Capture the opaque target identity when each stream starts and require that stored identity to match the request instead of re-resolving the stream key.

    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())
            : [];

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

[Adam Ratzman (adamint)]

Copilot review

[Copilot]

Review details

Suppressed comments (2)

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

extension/src/data/appHostPsPoller.ts:359

• Every follow line received during an authoritative snapshot sets the pending flag, and completion immediately starts another aspire ps process at line 349. With a continuously active ps --follow stream, each snapshot overlaps at least one update, so reconciliation becomes a back-to-back process loop instead of periodic polling. Debounce the retry until activity is quiet (or rely on the existing interval) rather than scheduling it immediately for every replayed delta.

        this._authoritativeSnapshotPending = true;

extension/src/dcp/types.ts:165

• For a direct Node/Bun launch, runtime_executable is optional and the debugger intentionally defaults to the runtime (node.ts:34-40). Returning no executable identity here means an active legacy/default-runtime session cannot match a resource whose snapshot reports executable.path as node or bun, so the status tool incorrectly returns notDebugging. Use the runtime type as the default identity when this field is absent.

    if (isJavaScriptRuntimeLaunchConfiguration(configuration)) {
        const runtimeExecutable = getNonEmptyPath(configuration.runtime_executable);
        return runtimeExecutable === undefined ? [] : [runtimeExecutable];

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

[Adam Ratzman (adamint)]

Copilot review

[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