feat: add custom blueprint permissions configuration and management

[sellakumaran]

This pull request introduces comprehensive support for configuring and managing custom API permissions ("custom blueprint permissions") for agent blueprints in Agent 365. The changes add new CLI options, update documentation, and enhance integration test coverage to enable users to specify, view, and reset custom permissions for both Microsoft Graph and custom APIs. The implementation ensures validation, idempotency, and user-friendly feedback throughout the workflow.

Key changes include:

CLI Enhancements for Custom Blueprint Permissions

• Added new options to the a365 config init command: --custom-blueprint-permissions, --resourceAppId, --scopes, --reset, and --force, allowing users to add, update, view, or clear custom API permissions directly from the CLI.
• Implemented parameter-based logic to handle custom permissions, including validation of GUIDs and scopes, duplicate detection, and interactive confirmation for overwrites. Updated permissions are saved to both local and global config files, with context-aware next-step guidance.

Documentation Updates

• Expanded usage instructions in Readme-Usage.md to cover custom blueprint permissions configuration, setup, and reset workflows, with CLI command examples and links to detailed guides. [1] [2]
• Updated the design documentation to describe the new custom permissions feature, including architecture, validation, usage scenarios, and references to design docs and GitHub issue Feature Request: CLI Support for Presence & Files API Permissions #194.

Integration Test Workflow Improvements

• Added new integration tests to integration-test-workflow.md for configuring, applying, and verifying custom blueprint permissions, including auto-lookup of resource names, Azure Portal validation, and Graph API verification of inheritable permissions. [1] [2] [3]

Other Improvements

• Improved endpoint cleanup logging by displaying the actual endpoint name (truncated as used in Azure) during deletion preview.

These changes provide a robust and user-friendly workflow for managing custom API permissions, supporting advanced agent scenarios and improving overall configuration transparency.

Closes #194

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Adds end-to-end support in the Agent 365 CLI for configuring and applying “custom blueprint permissions” (additional delegated OAuth scopes for Microsoft Graph and other resource APIs), including config storage, setup-time application, and updated docs/tests.

Changes:

• Introduces CustomResourcePermission model and wires customBlueprintPermissions into Agent365Config validation and cloning.
• Adds a365 config permissions to manage custom permissions in a365.config.json, and adds a365 setup permissions custom (plus setup all / setup blueprint integration) to apply them.
• Adds/updates tests and documentation for the new workflow, including auto-lookup of resource display names.

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Services/Helpers/EndpointHelperTests.cs	Minor test-file change (but currently breaks compilation due to missing Xunit import).
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Services/GraphApiServiceTests.cs	Adds unit tests for service-principal display-name lookup (needs handler disposal consistency).
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Services/ConfigurationWizardServicePermissionsTests.cs	New tests for interactive custom-permissions wizard step (currently missing Xunit import).
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Models/CustomResourcePermissionTests.cs	New tests for permission validation and add/update (currently missing Xunit import).
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Models/Agent365ConfigTests.cs	Adds config validation + JSON roundtrip tests for customBlueprintPermissions.
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/PermissionsSubcommandTests.cs	Updates command composition expectations and adds tests for skipping custom permissions.
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/ConfigPermissionsSubcommandTests.cs	New tests for a365 config permissions behavior (currently missing Xunit import).
src/Microsoft.Agents.A365.DevTools.Cli/Services/GraphApiService.cs	Disposes GET responses; adds GetServicePrincipalDisplayNameAsync with GUID validation.
src/Microsoft.Agents.A365.DevTools.Cli/Services/ConfigurationWizardService.cs	Adds wizard step to collect optional custom permissions and includes count in summary.
src/Microsoft.Agents.A365.DevTools.Cli/Models/CustomResourcePermission.cs	New model for resource appId + scopes, with validation and add/update helper.
src/Microsoft.Agents.A365.DevTools.Cli/Models/Agent365Config.cs	Adds validation and init-only CustomBlueprintPermissions; adds cloning helper.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/SetupResults.cs	Adds custom-permissions result flags for setup summary.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/SetupHelpers.cs	Extends setup summary and recovery hints for custom permissions.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/PermissionsSubcommand.cs	Adds setup permissions custom + core configuration logic with auto-lookup and fallback names.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/BlueprintSubcommand.cs	Applies custom permissions after blueprint setup when configured.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/AllSubcommand.cs	Adds “Step 5” in setup all to apply custom permissions when configured.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/ConfigSubcommands/PermissionsSubcommand.cs	New a365 config permissions subcommand to view/add/update/reset custom permissions.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/ConfigCommand.cs	Registers the new config permissions subcommand.
docs/design.md	Documents the feature (currently contains outdated command examples).
docs/commands/setup-permissions-custom.md	New guide for a365 setup permissions custom (needs clarification on persistence of resolved names).
docs/commands/config-init.md	Documents the new wizard step for custom permissions.
docs/ai-workflows/integration-test-workflow.md	Adds integration-test steps for custom permissions (currently claims persistence that doesn’t happen).
Readme-Usage.md	Adds usage examples and “custom permissions” section.
.gitignore	Ignores local diagnostics / review artifacts.

Comments suppressed due to low confidence (1)

src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Services/Helpers/EndpointHelperTests.cs:13

• using Xunit; was removed, but this file still uses [Fact]/[Theory]. There’s no global using Xunit; in the test project, so this will not compile. Re-add the using Xunit; (or add a single global using for the test project) to restore compilation.

using FluentAssertions;
using Microsoft.Agents.A365.DevTools.Cli.Exceptions;
using Microsoft.Agents.A365.DevTools.Cli.Services.Helpers;

namespace Microsoft.Agents.A365.DevTools.Cli.Tests.Services.Helpers;

public class EndpointHelperTests
{
    [Fact]
    public void GetEndpointName_WhenNameIsUnder42Chars_ReturnsOriginalName()