[WIP][not-for-review] azure.ai.agents: revamp next-step + doctor for unified azure.yaml

[antriksh30]

Summary

[WIP] [not-for-review] — This PR is not ready for review. It is staged ahead of the
unified-azure.yaml core changes and is intended to be finalized once that work lands.

Reworks the two azure.ai.agents extension features I previously shipped —
next-step suggestions (internal/cmd/nextstep/) and azd ai agent doctor
(internal/cmd/doctor/) — to source all state from the unified azure.yaml design
instead of the legacy three-file layout.

• Before: azure.yaml (host: azure.ai.agent + a config: block) + agent.yaml
  (runtime def) + agent.manifest.yaml (templated resources).
• After: a single azure.yaml service entry, host: microsoft.foundry, with
  deployments / connections / toolboxes / skills / routines / agents as
  top-level service properties (no config: indirection); per-agent runtime fields
  (project, docker, protocols, env, …) nest under agents[].

Design references: the product brief (preview repo simple/complex branches) and the
engineering spec #8590 (docs/specs/unify-azure-yaml/spec.md).

⚠️ Dependency / status

This change is gated on a separate workstream (core azure.yaml JSON-schema support for
host: microsoft.foundry, the new service-target registration, and the init rework). Until
that lands, these two features will be no-ops for existing (old-layout) projects — which
is expected and accepted. The code is structured so field-shape true-ups against the final
implementation are localized to one decode seam.

What changed

nextstep

• New nextstep/foundry_config.go — the single decode seam. Decodes
  ServiceConfig.AdditionalProperties (forwarded by core over gRPC, no env-subst) into a
  local read-model, and resolves data-side $ref: file includes with the spec's
  overlay overrides (sibling keys win) and project: path rebasing (relative to the
  referenced file). ${VAR} / ${{...}} are preserved verbatim.
• state.go — collectFoundry produces one ServiceState per agent (with Kind +
  owning ServiceName) plus aggregated model/toolbox/connection refs; host const →
  microsoft.foundry; an explicit endpoint: marks the project as present.
• Deleted manifest.go (the agent.manifest.yaml walker) and dropped {{ }}
  placeholder handling entirely; missing-var detection now scans agents[].env.
• resolver.go — removed the placeholder branch (switch 4 → 3 arms).

doctor

• Host const → microsoft.foundry; removed the now-obsolete local.agent-yaml-valid
  check (structural validity is covered by local.azure-yaml); repointed the
  manual-env-vars skip-cascade to local.agent-service-detected.
• Updated all user-facing strings/docs from agent.yaml / agent.manifest.yaml /
  azure.ai.agent → azure.yaml / microsoft.foundry.

tests

• Rewrote the affected tests against in-memory AdditionalProperties fixtures (preserving
  OpenAPI / Bicep-classification coverage); added decode-seam, protocol, env-ref, and
  resource-aggregation tests.

Scope

Touches only internal/cmd/nextstep/ and internal/cmd/doctor/ (+ their tests). Does
not touch init.go, listen.go, or service_target_agent.go — those belong to the
unification workstream.

Verification

• go build ./... ✅
• go test ./internal/... ✅ (whole extension)
• golangci-lint run (nextstep + doctor) ✅ 0 issues
• cspell ✅ · gofmt -l clean · copyright headers present

Known true-ups (tracked in code comments)

• isDeployed assumes a per-agent AGENT_<KEY>_VERSION env var — verify against the new
  service target's actual convention (TODO(unify true-up) in state.go).
• Nested-$ref / instructions path rebasing intentionally out of scope (not consumed by
  nextstep).

[microsoft-github-policy-service]

Hi @@antriksh30. Thank you for your interest in helping to improve the Azure Developer CLI experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

[microsoft-github-policy-service]

Hi @@antriksh30. Thank you for your contribution. Since there hasn't been recent engagement, we're going to close this out. Feel free to respond with a comment containing "/reopen" if you'd like to continue working on these changes. Please be sure to use the command to reopen or remove the "no-recent-activity" label; otherwise, this is likely to be closed again with the next cleanup pass.