pi-azure-devops

Azure DevOps diagnostics for Pi and OMP.

Use your coding agent to inspect Azure DevOps builds, fetch bounded logs, list artifacts, and safely preview artifact downloads without giving the agent Azure DevOps mutation powers.

What you can do

• Check Azure DevOps configuration and token readiness.
• Inspect build status and timeline failures.
• Fetch logs by build, stage, job, task, or explicit log ID.
• Diagnose failed builds with timeline issues and selected log evidence.
• List recent pipelines, recent builds, and build artifacts.
• Preview artifact downloads before writing anything locally.
• Run mock diagnostics with no network access and no token.

Safety model

This package is intentionally conservative:

• Azure DevOps operations are read-only: no queue, cancel, rerun, approval, or remote mutation APIs are exposed.
• Artifact download is local-write only. It writes under the current workspace only after an explicit confirmation flag or confirm: true.
• Artifact download previews write nothing.
• Output paths reject absolute paths, traversal outside the workspace, Windows drive prefixes, UNC prefixes, and NUL bytes.
• ZIP extraction preflights entries for Zip Slip and file/directory conflicts before writing.
• PATs, auth headers, and signed URL secrets are redacted from output and errors.
• Pipeline artifact signed URLs are fetched without the Azure DevOps Authorization header.
• Mock mode uses local fixtures and does not require credentials.

Install in OMP

omp plugin install @rxreyn3/pi-azure-devops
omp plugin doctor --json

Then start OMP and ask for an Azure DevOps diagnostic task. For example:

Use the Azure DevOps extension in mock mode to diagnose build 101 and summarize the failed task.

Use Azure DevOps diagnostics to list artifacts for build 101 in mock mode. Do not download anything.

Install in Pi

Pi package installs use the npm source prefix:

pi install npm:@rxreyn3/pi-azure-devops

To try the package for one run without adding it to settings:

pi -e npm:@rxreyn3/pi-azure-devops

What this adds to Pi/OMP

Installing the package registers these resources from package.json:

| Resource | What it provides | | --- | --- | | Extension | Azure DevOps tools callable by the agent | | Skill | Safe Azure DevOps operating rules and missing-info behavior | | Prompt templates | Reusable ado-* workflows for doctor, status, logs, artifacts, and diagnose tasks | | CLI | pi-ado, a standalone command line interface for the same core operations |

The extension tools are:

| Tool | Purpose | | --- | --- | | azure_devops_doctor | Check resolved config and auth readiness | | azure_devops_get_status | Fetch build status and timeline summary | | azure_devops_get_logs | Fetch bounded selected log content | | azure_devops_diagnose_failure | Collect failure evidence from status, timeline, logs, and artifact metadata | | azure_devops_list_artifacts | List build artifact metadata | | azure_devops_list_pipelines | List recent pipeline summaries | | azure_devops_list_builds | List recent build summaries | | azure_devops_download_artifact | Preview or confirm a local artifact ZIP download/extract |

First run without credentials

Use mock mode to verify the package and see the shape of responses without touching Azure DevOps:

pi-ado doctor --mock --json
pi-ado status --mock --build-id 101 --json
pi-ado diagnose --mock --build-id 101 --json

Mock mode is also useful inside Pi/OMP prompts:

Use Azure DevOps diagnostics in mock mode to explain build 101.

Configure Azure DevOps access

Live Azure DevOps calls need an organization, project, and token. The fastest setup is environment variables:

export PI_AZURE_DEVOPS_ORGANIZATION="<your-org-or-url>"
export PI_AZURE_DEVOPS_PROJECT="<your-project>"
export PI_AZURE_DEVOPS_PAT="<your-pat>"

Supported token environment variables, in lookup order:

1. PI_AZURE_DEVOPS_PAT
2. PI_ADO_PAT
3. AZURE_DEVOPS_PAT
4. AZURE_DEVOPS_EXT_PAT
5. ADO_PAT
6. SYSTEM_ACCESSTOKEN

For file-based profiles and the full resolution order, see docs/configuration.md.

Common agent requests

After installation, ask Pi/OMP for the outcome you want rather than for a specific REST call:

Diagnose Azure DevOps build 12345 and explain the most likely failure cause.

Fetch the log for task name "Build" in Azure DevOps build 12345. Keep the output bounded.

List artifacts for Azure DevOps build 12345 and tell me which one looks like the drop artifact.

Preview downloading artifact "drop" from build 12345 to artifacts/drop.zip. Do not confirm the write.

Download artifact "drop" from build 12345 to artifacts/drop.zip only after showing me the preview and asking for confirmation.

CLI reference

The pi-ado CLI is available for shell workflows and for smoke testing outside the agent.

pi-ado doctor [--json] [--mock]

pi-ado status --build-id <id> \
  [--stage-id <guid>] [--stage-name <name>] \
  [--job-id <guid>] [--job-name <name>] \
  [--task-id <guid>] [--task-name <name>] \
  [--json] [--mock]

pi-ado logs --build-id <id> \
  [--stage-id <guid>] [--stage-name <name>] \
  [--job-id <guid>] [--job-name <name>] \
  [--task-id <guid>] [--task-name <name>] \
  [--log-id <id>] [--max-bytes <n>] \
  [--start-line <n>] [--end-line <n>] \
  [--json] [--mock]

pi-ado diagnose --build-id <id> \
  [--stage-id <guid>] [--stage-name <name>] \
  [--job-id <guid>] [--job-name <name>] \
  [--task-id <guid>] [--task-name <name>] \
  [--log-id <id>] [--max-bytes <n>] \
  [--start-line <n>] [--end-line <n>] \
  [--json] [--mock]

pi-ado artifacts --build-id <id> [--json] [--mock]

Timeline display-name selectors

status, logs, and diagnose accept human-readable selectors in addition to ID/GUID selectors:

• CLI: --stage-name, --job-name, --task-name
• Extension tools: stageName, jobName, taskName

Name matching is exact, then case-insensitive exact, then substring. Ambiguous matches return candidates and do not auto-pick a record. Stage selectors provide status/evidence context only; they do not infer a child job/task log.

Local artifact download

pi-ado artifacts download \
  --build-id <id> \
  --artifact-name <name> \
  --output <relative-path> \
  [--artifact-kind auto|build|pipeline] \
  [--pipeline-id <id>] [--run-id <id>] \
  [--max-bytes <n>] \
  [--confirm] [--extract] [--overwrite] \
  [--json] [--mock]

Behavior:

• Without --confirm, the command prints a preview and writes nothing.
• With --confirm, it downloads the artifact ZIP. Add --extract to extract entries into the destination directory.
• --artifact-kind auto checks both Build Artifacts and Pipelines Artifacts APIs. If both match, the preview reports ambiguous and refuses to write.
• Pipeline-source resolution defaults pipelineId = build.definitionId and runId = buildId; pass --pipeline-id / --run-id when auto-inference is not enough.
• Existing files are never overwritten without --overwrite.

Local development

npm install
npm test
npm run typecheck
npm run build
npm run --silent spike:rest -- --mock --json

npm run build generates the dist/ files used by the CLI binary and Pi extension metadata. dist/ stays gitignored and is regenerated by prepack for package tarballs.

Package and publication notes

• Published npm package: @rxreyn3/pi-azure-devops
• No custom registry mapping is required.
• GitHub Actions button publication and live-install steps are documented in docs/publication.md.
• Staged implementation history lives in generic-pi-azure-devops-plan.md.