feat(agents): resolve $ref file includes with overlay overrides in Foundry config

[huimiu]

What

Adds an extension-owned resolver for the azure.ai.agents extension that resolves $ref file includes within a parsed Foundry service configuration, implementing spec §2.4 of #8590 (docs/specs/unify-azure-yaml/spec.md).

ResolveFileRefs(cfg map[string]any, projectRoot string):

• Includes — any object containing a $ref string is replaced by the referenced YAML or JSON file (JSON parses as a subset of YAML, so one decoder handles both).
• Overlay overrides — keys alongside $ref are overlaid on the loaded file as a shallow, top-level merge: sibling scalars, arrays, and objects each replace the loaded value wholesale.
• Nested includes — $ref inside a loaded file resolves relative to that file's own directory.
• Path rebasing — each loaded file's relative project, instructions, and $ref paths are rebased so the returned config has every path anchored to projectRoot in clean, forward-slash form. Inline values authored directly in azure.yaml are left exactly as written. instructions is rebased only when it looks like a path (single line ending in .md/.txt), so inline prose is preserved.
• Whitespace trimming — $ref values are trimmed of surrounding whitespace before path resolution, so " ./agents/a.yaml " resolves correctly.
• Safety — cyclic and excessively deep include chains return actionable errors (cycle detection uses slices.Contains/slices.Clone for correctness); URL $ref targets are rejected; unreadable or malformed files produce structured exterrors validation errors.

This is a self-contained helper plus thorough tests, mirroring the merged ${...} templating helper (#8602). There is no product call-site yet — the consumer is the not-yet-built microsoft.foundry service target (§2.2/§2.6).

Testing

• go build ./..., go vet ./..., gofmt, golangci-lint run (0 issues), go test ./... (full extension suite), and cspell — all clean.
• 16 test cases cover: nil config, no-op, relative/absolute/JSON includes, $ref whitespace trimming, sibling overlay, nested includes, top-level sequence files, project/instructions rebasing, inline-vs-path instructions, and the missing-file / malformed / cyclic / URL / non-string / empty-$ref error paths.

Fixes #8626

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Review may take a bit longer — reach out to @rajeshkamal5050 or @kristenwomack if you'd like to discuss prioritization.

[Copilot]

Pull request overview

Adds a new helper in the azure.ai.agents extension to resolve Foundry $ref file includes inside already-parsed service configuration data, including shallow sibling overlays, nested include resolution, path rebasing, and structured validation errors.

Changes:

• Added ResolveFileRefs implementation to recursively resolve $ref YAML/JSON includes, apply shallow overlays, and rebase certain paths to the project root.
• Added table-driven unit tests covering includes, overlays, rebasing behavior, and common error cases (missing/malformed/cyclic/URL/non-string/empty refs).
• Introduced a new extension error code for invalid $ref usage (invalid_file_ref).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
cli/azd/extensions/azure.ai.agents/internal/project/includes.go	New $ref resolver implementation (load, overlay, recurse, rebase, cycle/depth safety).
cli/azd/extensions/azure.ai.agents/internal/project/includes_test.go	Table-driven tests validating include resolution, rebasing rules, and error handling.
cli/azd/extensions/azure.ai.agents/internal/exterrors/codes.go	Adds CodeInvalidFileRef error code for structured validation errors.