Add an official diagnostics capability to the Agentstration Assistant

[gbaudrit]

Area

Runtime

Feature type

User-facing capability

Problem or need

The official Assistant needs a diagnostic capability distinct from documentation Q&A and Resource Planning. Users should be able to ask why a configuration, Flow, provider, Source, extension, or execution is not behaving as expected without teaching the Assistant unrestricted mutation or raw internal Resource contracts.

Expected outcome

A specialized diagnostics capability can inspect bounded authorized operational/read-model information, explain likely causes, surface relevant evidence, and suggest safe navigation or next actions. It is invokable as a child Flow of the official Assistant and remains useful independently.

Proposed solution

Create a diagnostics Flow with specialist Agent instructions and governed read-only diagnostic Tools/projections. Prefer stable domain diagnostics/read models over exposing storage DTOs or generic database/resource access. Structured results may include findings, references, and safe navigation suggestions.

Scope

• Diagnostic intent contract and child Flow.
• Specialist Agent instructions for troubleshooting Agentstration behavior.
• Governed read-only access to relevant health/status/diagnostic projections.
• Evidence-backed findings with stable severity/category where practical.
• Safe Console/Workplace navigation references through structured results.
• Explicit distinction between observation, hypothesis, and confirmed validation errors.
• Bounded fallback when evidence is insufficient.
• Authorization, redaction, causality, tests, documentation.

Out of scope

• Generic unrestricted Resource CRUD or database querying.
• Autonomous corrective mutation.
• Fabricating conclusions when diagnostics are unavailable.
• Replacing canonical validators or provider health checks.

Dependencies

Parent: #344.
Integrates with #346 and the structured-result work in #318 where available.
Uses existing diagnostics/status APIs and governed Tool infrastructure; missing bounded diagnostic projections may be added as implementation prerequisites.

Deployment impact

Configuration change

Acceptance criteria

• Representative Agentstration troubleshooting questions can be routed to the diagnostics capability.
• Diagnostic evidence comes from governed authorized read boundaries, not unrestricted internal access.
• Findings distinguish observed facts from inferred hypotheses.
• Sensitive content/secrets are not exposed in prompts, results, logs, or structured findings.
• The capability can suggest safe navigation or follow-up actions without mutating configuration automatically.
• Insufficient evidence produces a bounded response rather than invented diagnosis.
• The capability is independently invokable and composable under the Assistant router.
• Tests cover authorization, unavailable diagnostics, representative failures, redaction, and structured results.

Preliminary checks

• I searched for an existing issue covering this request.