Stabilize the behavior and reliability of ExternalProcessService

[anuchandy]

What does this PR do?

[Provide a clear, concise description of the changes]

[Any additional context, screenshots, or information that helps reviewers]

GitHub issue number?

[Link to the GitHub issue this PR addresses]

Pre-merge Checklist

• Required for All PRs
  • Read contribution guidelines
  • PR title clearly describes the change
  • Commit history is clean with descriptive messages (cleanup guide)
  • Added comprehensive tests for new/modified functionality
  • Updated servers/Azure.Mcp.Server/CHANGELOG.md and/or servers/Fabric.Mcp.Server/CHANGELOG.md for product changes (features, bug fixes, UI/UX, updated dependencies)
• For MCP tool changes:
  • One tool per PR: This PR adds or modifies only one MCP tool for faster review cycles
  • Updated servers/Azure.Mcp.Server/README.md and/or servers/Fabric.Mcp.Server/README.md documentation
  • Validate README.md changes using script at eng/scripts/Process-PackageReadMe.ps1. See Package README
  • Updated command list in /servers/Azure.Mcp.Server/docs/azmcp-commands.md and/or /docs/fabric-commands.md
  • Run .\eng\scripts\Update-AzCommandsMetadata.ps1 to update tool metadata in azmcp-commands.md (required for CI)
  • For new or modified tool descriptions, ran ToolDescriptionEvaluator and obtained a score of 0.4 or more and a top 3 ranking for all related test prompts
  • For tools with new names, including new tools or renamed tools, update consolidated-tools.json
  • For new tools associated with Azure services or publicly available tools/APIs/products, add URL to documentation in the PR description
• Extra steps for Azure MCP Server tool changes:
  • Updated test prompts in /servers/Azure.Mcp.Server/docs/e2eTestPrompts.md
  • 👉 For Community (non-Microsoft team member) PRs:
    • Security review: Reviewed code for security vulnerabilities, malicious code, or suspicious activities before running tests (crypto mining, spam, data exfiltration, etc.)
    • Manual tests run: added comment /azp run mcp - pullrequest - live to run Live Test Pipeline

[anuchandy]

adding notes

[Copilot]

Pull Request Overview

This PR refactors the ExternalProcessService to improve reliability, thread safety, and cancellation handling. The service now properly distinguishes between timeouts and cancellations, uses event-driven asynchronous stream reading, and provides comprehensive diagnostic information on failures.

Key Changes

• Refactored ExecuteAsync to use Task.WaitAsync for timeout handling instead of synchronous waits with AutoResetEvents
• Changed API signature: removed SetEnvironmentVariables method, replaced customPaths parameter with environmentVariables parameter passed directly to ExecuteAsync
• Implemented ProcessStreamReader for proper async stream capture with event-driven reading
• Added extensive documentation and diagnostic information to exceptions via the Data dictionary

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
IExternalProcessService.cs	Updated interface: renamed parameters, removed SetEnvironmentVariables method, added comprehensive XML documentation
ExternalProcessService.cs	Complete rewrite: async stream readers, timeout vs cancellation distinction, safe process inspection utilities, extensive exception diagnostics
CommandMetadataSyncTests.cs	Updated to pass NullLogger to ExternalProcessService constructor (now required)
AzqrCommand.cs	Updated call to ExecuteAsync with null for environmentVariables parameter
AzCommand.cs	Updated calls to ExecuteAsync with null for environmentVariables parameter
AzqrCommandTests.cs	Updated mock setup to match new ExecuteAsync signature

Comments suppressed due to low confidence (1)

servers/Azure.Mcp.Server/tests/Azure.Mcp.Server.UnitTests/Infrastructure/CommandMetadataSyncTests.cs:39

• Missing required parameter in method call. The new ExecuteAsync signature requires environmentVariables and operationTimeoutSeconds parameters between arguments and cancellationToken. The call should be: await processService.ExecuteAsync(pwshPath, arguments, null, 300, cancellationToken: TestContext.Current.CancellationToken) or use named arguments for clarity.

        var updateResult = await processService.ExecuteAsync(pwshPath, arguments, cancellationToken: TestContext.Current.CancellationToken);