debug-agent

# Debug Agent Diagnose a pipeline failure or customer issue end-to-end. Accepts a log file path, pasted error text, ADO work item ID, or GitHub issue URL. Determines ownership, resolves if PPBT-owned, or produces a precise triage package for the right team. Invoke as: `/debug-agent <log-file-path | error-text | issue-url | ado-id>` **Works autonomously through all steps. One exception: pauses to request pipeline logs if they are referenced in an ICM/work item but not yet provided — log evidence is required before classifying the failure layer.** --- ## Step 0 — Ingest the input Determine input type: - **File path** (`.txt`, `.log`, or similar): read it with the `Read` tool - **ADO work item** (`dev.azure.com/...` URL or bare integer): `az boards work-item show --id <id> 2>&1` - **GitHub issue** (`github.com/.../issues/<n>`): `gh issue view <n> --comments 2>&1` - **Pasted text**: use as-is Extract and print: ```text Input summary: - Type: <file | ado | github | text> - Task/tool identified: <name from log header, or "unknown"> - Error snippet: <first clear error line, or "none found"> - Timestamp range: <start → end> - Deployment result: <SUCCESS | FAILED | unknown> ``` ### Step 0b — Check for missing logs If input is an ICM or ADO work item AND any of the following are true: - Custom field `LogsAttached` = `"Yes"` - Description mentions "logs attached" or "see attachment" - Issue cannot be diagnosed from text alone (no error snippet, no pac CLI output visible) AND no log file path or log content was provided by the user: → **STOP. Prompt the user:** ``` Pipeline logs are attached to this ICM/work item but aren't accessible via API. Please download the logs from the portal and provide the folder path. Example: C:\Users\<you>\Downloads\ Once you share the path, I'll read the logs and continue the analysis from Step 1. ``` **Do not proceed to Step 1 until log content is available. Do NOT classify the failure layer, assign ownership, or draw conclusions based solely on the ICM title or description — log evidence is mandatory.** If the user confirms no logs exist or they are unavailable, continue with `Confidence: low` noted throughout. --- ## Step 1 — Verify PPBT is involved ### ADO (Azure DevOps) — PPBT task identifiers Every PPBT v2 task follows the pattern: `microsoft-IsvExpTools.PowerPlatform-BuildTools.<task-id>.<TaskClass>@2` | Display Name | Task ID (in YAML/log) | Task Class | |---|---|---| | Power Platform Tool Installer | `tool-installer` | `PowerPlatformToolInstaller@2` | | Power Platform WhoAmI | `whoami` | `PowerPlatformWhoAmi@2` | | Power Platform Checker | `checker` | `PowerPlatformChecker@2` | | Power Platform Import Solution | `import-solution` | `PowerPlatformImportSolution@2` | | Power Platform Export Solution | `export-solution` | `PowerPlatformExportSolution@2` | | Power Platform Unpack Solution | `unpack-solution` | `PowerPlatformUnpackSolution@2` | | Power Platform Pack Solution | `pack-solution` | `PowerPlatformPackSolution@2` | | Power Platform Delete Solution | `delete-solution` | `PowerPlatformDeleteSolution@2` | | Power Platform Add Solution Component | `add-solution-component` | `PowerPlatformAddSolutionComponent@2` | | Power Platform Apply Solution Upgrade | `apply-solution-upgrade` | `PowerPlatformApplySolutionUpgrade@2` | | Power Platform Publish Customizations | `publish-customizations` | `PowerPlatformPublishCustomizations@2` | | Power Platform Set Solution Version | `set-solution-version` | `PowerPlatformSetSolutionVersion@2` | | Power Platform Set Connection Variables | `set-connection-variables` | `PowerPlatformSetConnectionVariables@2` | | Power Platform Deploy Package | `deploy-package` | `PowerPlatformDeployPackage@2` | | Power Platform Create Environment | `create-environment` | `PowerPlatformCreateEnvironment@2` | | Power Platform Delete Environment | `delete-environment` | `PowerPlatformDeleteEnvironment@2` | | Power Platform Assign User | `assign-user` | `PowerPlatformAssignUser@2` | | Power Platform Reset Environment | `reset-environment` | `PowerPlatformResetEnvironment@2` | | Power Platform Backup Environment | `backup-environment` | `PowerPlatformBackupEnvironment@2` | | Power Platform Copy Environment | `copy-environment` | `PowerPlatformCopyEnvironment@2` | | Power Platform Restore Environment | `restore-environment` | `PowerPlatformRestoreEnvironment@2` | | Export Dataverse Data | `export-data` | `PowerPlatformExportData@2` | | Import Dataverse Data | `import-data` | `PowerPlatformImportData@2` | | Power Platform Download PAPortal | `download-paportal` | `PowerPlatformDownloadPaportal@2` | | Power Platform Upload PAPortal | `upload-paportal` | `PowerPlatformUploadPaportal@2` | **PPBT signals** (any one is sufficient): - Task class matches any entry in the table above - Author is `Microsoft` (not `Wael Hamze` or other community authors) - Log contains `POWERPLATFORMTOOLS_PACCLIPATH` or `PP_TOOLS_AUTOMATION_AGENT` - pac CLI invoked: lines containing `pac solution`, `pac auth`, `pac env`, `pac admin`, `pac package` - `BuildTools.EnvironmentUrl` pipeline variable present ### GitHub Actions — PPBT action identifiers All PPBT GitHub Actions use: `microsoft/powerplatform-actions/<action-name>@v1` | Action | `uses:` value | |---|---| | Install Power Platform Tools | `microsoft/powerplatform-actions/actions-install@v1` | | WhoAmI | `microsoft/powerplatform-actions/whoAmI@v1` | | Import Solution | `microsoft/powerplatform-actions/import-solution@v1` | | Export Solution | `microsoft/powerplatform-actions/export-solution@v1` | | Unpack Solution | `microsoft/powerplatform-actions/unpack-solution@v1` | | Pack Solution | `microsoft/powerplatform-actions/pack-solution@v1` | | Publish Customizations | `microsoft/powerplatform-actions/publish-solution@v1` | | Clone Solution | `microsoft/powerplatform-actions/clone-solution@v1` | | Check Solution | `microsoft/powerplatform-actions/check-solution@v1` | | Upgrade Solution | `microsoft/powerplatform-actions/upgrade-solution@v1` | | Deploy Package | `microsoft/powerplatform-actions/deploy-package@v1` | | Upload PAPortal | `microsoft/powerplatform-actions/upload-paportal@v1` | | Catalog Install | `microsoft/powerplatform-actions/install@v1` | | Catalog Submit | `microsoft/powerplatform-actions/submit@v1` | | Catalog Status | `microsoft/powerplatform-actions/status@v1` | **Not-PPBT signals — deflect immediately:** - Author: `Wael Hamze` → CRM Build Tools (community) - `Microsoft.Xrm.Tooling.*` PowerShell → old XRM Tooling - `PackageDeployer` PowerShell task (v12.x) → Wael Hamze legacy tooling - Task version `@v1` **and** no `microsoft/powerplatform-actions` prefix → unrelated action If **not PPBT**: skip to Step 5 (non-PPBT triage) immediately. --- ## Step 2 — Identify the failing task and classify the layer ### 2a — Map the failing task to its inputs Use the tables below to check whether required inputs are present in the log or YAML. #### Helper tasks **Tool Installer** (`tool-installer`) — must be FIRST task in every pipeline/workflow - No required inputs beyond defaults - Critical: if missing → all other tasks fail with "pac.exe not found" or `POWERPLATFORMTOOLS_PACCLIPATH not set` - Optional: `AddToolsToPath: true` (adds pac to PATH for script tasks) **WhoAmI** (`whoami` / `whoAmI`) - Required: `authenticationType` + one of `PowerPlatformEnvironment` or `PowerPlatformSPN` - GitHub: `environment-url` + auth credentials (`user-name`/`password-secret` OR `app-id`/`client-secret`/`tenant-id`) - Use: connectivity check early in pipeline — failure here = auth or network issue, not solution issue #### Quality check **Checker** (`checker` / `check-solution`) - Required: `PowerPlatformSPN` (SPN only — username/password NOT supported for checker) - Required: `RuleSet` GUID - Optional: `UseDefaultPACheckerEndpoint` (default true) — if false, must set `CustomPACheckerEndpoint` - Output: SARIF file as pipeline artifact (`ArtifactDestinationName`) - Common issue: checker fails for username/password connections — SPN required #### Solution tasks **Import Solution** (`import-solution`) - Required: service connection + `SolutionInputFile` - Key options: `AsyncOperation: true` (recommended for large solutions — avoids 4-min timeout), `HoldingSolution` (for upgrade pattern), `UseDeploymentSettingsFile` (for connection references + env vars) - Common issue: sync import times out on large solutions → set `AsyncOperation: true`, `MaxAsyncWaitTime: 60` - Common issue: connection references not set → use `DeploymentSettingsFile` **Export Solution** (`export-solution`) - Required: service connection + `SolutionName` + `SolutionOutputFile` - Note: use solution *Name* not *Display Name* - `Managed: true` exports as managed **Apply Solution Upgrade** (`apply-solution-upgrade`) - Required: service connection + `SolutionName` - Use after Import with `HoldingSolution: true` **Pack / Unpack Solution** — local operations, no service connection needed - `SolutionType`: Managed | Unmanaged | Both **Set Solution Version** (`set-solution-version`) - Required: service connection + `SolutionName` + `SolutionVersionNumber` - Tip: use `$(Build.BuildId)` as version number **Set Connection Variables** (`set-connection-variables`) - Sets pipeline variables: `BuildTools.TenantId`, `BuildTools.ApplicationId`, `BuildTools.ClientSecret`, `BuildTools.DataverseConnectionString` - Username/password auth also requires `ApplicationId` and `RedirectUri` **Deploy Package** (`deploy-package`) - Required: service connection + `PackageFile` (.dll) - GitHub Actions: Windows runner only (`runs-on: windows-latest`) #### Environment management tasks **Create Environment** (`create-environment`) - Required: `DisplayName`, `LocationName`, `EnvironmentSku`, `CurrencyName`, `LanguageName`, `DomainName` - Side effect: sets `BuildTools.EnvironmentUrl` pipeline variable — subsequent tasks use this automatically - Note: `BuildTools.EnvironmentUrl` overrides any service connection URL for downstream tasks **Copy Environment** (`copy-environment`) - Required: `TargetEnvironmentUrl` - `CopyType`: FullCopy (data + metadata) or MinimalCopy (metadata only) **Restore Environment** (`restore-environment`) - `RestoreLatestBackup: true` OR provide `RestoreTimeStamp` in `mm/dd/yyyy hh:mm` format **Export/Import Dataverse Data** - Schema file created via Configuration Migration tool - Import accepts zip file or folder with `data-schema.xml` + `data.xml` #### Power Pages tasks - `download-paportal` / `upload-paportal`: requires `WebsiteId` GUID, optional `ModelVersion` (1=standard, 2=enhanced data model) ### 2b — When is it a PPBT bug (this repo)? PPBT owns exactly the boundary between the ADO/GitHub pipeline and cli-wrapper. A bug is PPBT's if the **wrong value reaches cli-wrapper** or **no value reaches cli-wrapper** when the user configured the pipeline correctly. **PPBT owns it — fix in this repo — when:** | Symptom | Root cause | File to fix | |---------|-----------|------------| | Task input exists in task.json but is silently ignored / not passed to pac | `index.ts` doesn't read it via `parameterMap` | `src/tasks/<name>/index.ts` | | Task input works on Windows but breaks on Linux (path, binary location) | `CliLocator.ts` platform logic | `src/host/CliLocator.ts` | | Wrong cloud instance sent to pac for a valid service connection | `resolveCloudInstance()` missing a cloud mapping | `src/params/auth/getCredentials.ts` | | `BuildTools.EnvironmentUrl` not set after `create-environment` runs | `index.ts` not calling `tl.setVariable` | `src/tasks/create-environment/index.ts` | | Service connection field (e.g. `tenantId`) extracted as null/undefined | `getCredentials.ts` reading wrong endpoint field | `src/params/auth/getCredentials.ts` | | Environment URL fallback chain skips a valid source | `getEnvironmentUrl.ts` fallback order wrong | `src/params/auth/getEnvironmentUrl.ts` | | Tasks appear in wrong pipeline stage / wrong task GUIDs | GUID substitution bug in pack step | `gulp/pack.mjs`, `extension/task-metadata.json` | | Tool installer fails to download pac or set `POWERPLATFORMTOOLS_PACCLIPATH` | Installer task logic | `src/tasks/tool-installer/index.ts` | | New task input added to `task.json` but not wired through to pac | `index.ts` `parameterMap` not updated | `src/tasks/<name>/index.ts` | | Task breaks after cli-wrapper version bump (interface mismatch) | `BuildToolsHost` or `BuildToolsRunnerParams` out of sync | `src/host/BuildToolsHost.ts`, `src/host/BuildToolsRunnerParams.ts` | | Error message from task is unhelpful / missing context | Better error surfacing needed | `src/tasks/<name>/index.ts` | **PPBT does NOT own it — do not fix in this repo — when:** | Symptom | Actual owner | |---------|-------------| | User forgot to add tool-installer to pipeline | User/pipeline config — document the fix, no code change | | User passed solution display name instead of unique name | User error | | cli-wrapper assembles wrong pac args (but PPBT passed the right values to it) | cli-wrapper repo | | pac CLI crashes or returns a wrong result | pac CLI / admin-tools | | Dataverse operation fails (solution import engine, HTTP 5xx) | CDS / Solution Framework | | Auth fails because service connection credentials are wrong/expired | User / service connection admin | | MFA required on username/password connection | User — must switch to SPN | **The test:** ask "If the user configured the pipeline exactly right, would this still fail?" If yes → PPBT bug. If no → user error or downstream team. ### 2c — Classify the failure layer ``` Azure DevOps / GitHub Actions pipeline → [L1] user/pipeline config error (task ordering, missing inputs, wrong auth type) → [L2] PPBT code bug (src/tasks/<name>/index.ts, getCredentials.ts, CliLocator.ts, etc.) → [L3] cli-wrapper bug (@microsoft/powerplatform-cli-wrapper/dist/actions/) → [L4] pac CLI binary (pac.exe / pac) └─ [L4-admin] pac env/admin commands → admin-tools team └─ [L4-pac] pac CLI crash / .NET exception → pac CLI team └─ [L4→L5] pac correctly relays Dataverse error → CDS team → [L5] Power Platform API (Dataverse / crm.dynamics.com) ``` | Symptom | Layer | Owner | |---------|-------|-------| | `pac.exe not found` / `POWERPLATFORMTOOLS_PACCLIPATH not set` | L1 | User — tool-installer step missing | | `BuildTools.EnvironmentUrl` targets wrong env | L1 | User — task ordering side effect | | Required input missing because user left it blank | L1 | User — pipeline config | | Checker fails with username/password | L1 | User — SPN required for checker | | Import times out (~4 min) on large solution | L1 | User — set `AsyncOperation: true` | | Input exists in task.json but is ignored / not passed to pac | L2 | **PPBT bug** — `index.ts` parameterMap | | `resolveCloudInstance()` returns wrong cloud for valid endpoint | L2 | **PPBT bug** — `getCredentials.ts` |