Skip to content

[Accounts] Add PowerShell error recovery CmdLets - #1484

Closed
Björn Sundling (bjompen) wants to merge 6 commits into
Azure:mainfrom
bjompen:main
Closed

Björn Sundling (bjompen) wants to merge 6 commits into
Azure:mainfrom
bjompen:main

Conversation

@bjompen

@bjompen Björn Sundling (bjompen) commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Description

resolves #1483

This pull request introduces a new PowerShell-based AI recovery feature for AzCLIPS, adding two new cmdlets and supporting infrastructure to help users recover from errors by sending diagnostic data to Azure AI and retrieving recovery advice. It also includes new embedded prompt templates, comprehensive help documentation, and tests.

  • Added two new cmdlets: Get-AzRecoveryId (lists recent AzCLIPS errors with recovery IDs) and Send-AzRecovery (sends a selected error to Azure AI for troubleshooting advice). [1] [2] [3]

  • Added embedded prompt templates for both "oneshot" and "interactive" recovery sessions, guiding Azure AI to provide context-appropriate troubleshooting advice based on the existing markdown templates for az cli recovery commands. [1] [2]

  • Added PlatyPS-based help files for both Get-AzRecoveryId and Send-AzRecovery, including syntax, usage, and parameter details. [1] [2]

Testing Guide

  • Introduced tests for the new recovery cmdlets, covering error listing, ID stability, and correct AI prompt selection and posting.

  • The PR title starts with [Component Name] for customer-facing changes or {Component Name} for non-customer-facing changes, and does not end with trailing punctuation or spaces.
  • Customer-facing changes include a useful release note in the PR title or the History Notes section.
  • I added or updated tests for behavior changes.
  • I updated documentation when behavior, setup, support, or security guidance changed.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 22:34
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
5 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Recovery IDs survive configuration resets, interactive recovery can hide answers or fail in noninteractive hosts, and requests omit diagnostic context and reasoning settings.

8 open issues
What changed in this PR

Adds manually invoked AI-assisted error recovery to the Accounts PowerShell module, extending AzCLIPS recovery workflows beyond the CLI.

Changes:

  • Adds Get-AzRecoveryId and Send-AzRecovery for selecting session errors and requesting recovery advice.
  • Supports one-shot and interactive conversations with PowerShell-specific prompts and builtin Azure AI integration.
  • Adds cmdlet help and tests for error filtering, stable IDs, and prompt/request handling.
File Description
tests/​Cmdlets.Tests/​RecoveryCmdletTests.cs Tests error listing, stable IDs, and model requests.
src/​PS/​Accounts/​RecoveryPrompts/​oneshot.md Defines single-response troubleshooting guidance.
src/​PS/​Accounts/​RecoveryPrompts/​interactive.md Defines conversational troubleshooting guidance.
src/​PS/​Accounts/​help/​Send-AzRecovery.md Documents setup, parameters, and recovery usage.
src/​PS/​Accounts/​help/​Get-AzRecoveryId.md Documents session error listing and recovery IDs.
src/​PS/​Accounts/​Cmdlets/​SendRecoveryCmdlet.cs Sends diagnostics and manages recovery conversations.
src/​PS/​Accounts/​Cmdlets/​GetRecoveryIdCmdlet.cs Filters session errors and assigns stable recovery IDs.
src/​PS/​Accounts/​Cmdlets.Accounts.csproj Includes endpoint resolution and embeds prompts.
src/​PS/​Accounts/​Accounts.psd1 Exports both recovery cmdlets.

Review effort: Balanced

Comment thread src/PS/Accounts/help/Send-AzRecovery.md Resolved
Increased the HttpClient timeout to 10 minutes.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 07:06

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Raw error text can send secret query parameters to the model without informed confirmation, and interactive recovery and configuration handling have unresolved defects.

8 open issues
4 previously missed issues

In code that hasn't changed since last review

Medium severity Snapshot $Error before yielding recovery IDs

src/​PS/​Accounts/​Cmdlets/​GetRecoveryIdCmdlet.cs:36

$Error is a mutable collection, and WriteObject runs downstream pipeline commands while this enumeration is still in progress. For example, Get-AzRecoveryId | ForEach-Object { Write-Error $_.Error } adds to $Error and invalidates the enumerator after the first result. Snapshot the entries before yielding them so downstream errors do not abort the listing.

Medium severity Document the Az.Config dependency for enabling recovery

src/​PS/​Accounts/​Cmdlets/​SendRecoveryCmdlet.cs:45

Set-AzConfig is exported by the separately installed preview Az.Config module, not by Az.Accounts. Standalone Accounts or leaf-module users therefore cannot follow these instructions to enable recovery, which defaults to off. Mention installing/importing the preview Config module here and in help/Send-AzRecovery.md:34–35.

Medium severity Refresh the access token before each interactive request

src/​PS/​Accounts/​Cmdlets/​SendRecoveryCmdlet.cs:69

accessToken is acquired once before the interactive loop and reused after arbitrary time spent at ReadLine(). If it expires while the user runs a suggested check, the next follow-up fails with 401 and the in-memory conversation is lost. Acquire a current token before each model request, using the auth service's token cache to refresh it when needed.

Medium severity Include sanitized service error details in HTTP failures

src/​PS/​Accounts/​Cmdlets/​SendRecoveryCmdlet.cs:120

When Azure AI rejects the configured model or API settings, EnsureSuccessStatusCode() reports only a status such as 400 Bad Request, omitting the service's error code and explanation. Surface a sanitized service error code/message and retain the HTTP status, with a fallback for non-JSON error bodies.

1 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 18, 2026 08:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread src/PS/Accounts/help/Send-AzRecovery.md Resolved
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 08:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Comment on lines +119 to +121
return $"Command: {cmdlet.Name}\nError category: {error.CategoryInfo.Category}" +
(kind is null ? "" : $"\nBinding error: {kind}") +
$"\nRecognized parameters: {string.Join(", ", parameters)}";
Copilot AI balanced review requested due to automatic review settings November 19, 2026 09:33
Snapshot recovery errors before output, suggest parameter names, and surface Azure AI error details with an HTTP status fallback. Remove the shared recovery reset hook to keep the PR scoped to the PowerShell recovery cmdlets.

Deferred (Azure#1484): turning recovery off does not invalidate PowerShell recovery IDs because tracking resets would require changes outside those cmdlets. HTTP status and service error codes are not reliably preserved because the existing error pipeline discards structured metadata, and shared services are intentionally unchanged.

Azure AI service error messages are not secret-redacted, matching the CLI approach at the user request; they may contain sensitive information.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

];
while (true)
{
var answer = SendAsync(s_http, endpoint, options, accessToken, messages, style, _cts.Token).GetAwaiter().GetResult();
AgentOptions options, Action<string> reportWarning, CancellationToken token)
{
var profile = await AzclipsServiceProvider.GetRequiredService<IProfileService>()
.GetActiveProfileAsync(token).ConfigureAwait(false)
Copilot AI balanced review requested due to automatic review settings November 19, 2026 09:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Recovery can send errors outside the opt-in/reset boundary, use the wrong tenant and regional endpoint, omit service error details, and fail when interactive tokens expire.

4 open issues
3 resolved since last review

Review effort: Balanced

Comment on lines +126 to +130
var status = error.Exception is HttpRequestException { StatusCode: { } statusCode }
? $"\nHTTP status: {(int)statusCode}" : "";
return $"Command: {cmdlet.Name}\nError category: {error.CategoryInfo.Category}" +
(kind is null ? "" : $"\nBinding error: {kind}") +
$"\nRecognized parameters: {string.Join(", ", parameters)}" +
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add AI assisted help to PowerShell CmdLets

3 participants