feat(azure.ai.agents): pending-provision reasons foundation (4.11)

Introduces an extension-owned signal — `AI_AGENT_PENDING_PROVISION` —
that lists resource-class tags `azd ai agent init` configured but Azure
has not yet materialized. This is the architectural foundation for
fixing a class of "trailer suggests azd deploy but provision is
actually needed" bugs that surface when init flows create new
resources inside an otherwise-existing Foundry project.

This commit lands the plumbing only — no behavior change yet. Init
code paths that mark resources for provisioning, and the resolver's
consumption of the list, follow in subsequent commits (B = model
deployment, C = project tag, D = ACR + AppInsights).

Architecture

  AI_AGENT_PENDING_PROVISION is a comma-separated, sorted,
  deduplicated tag list. Empty/unset = nothing pending. Tag taxonomy
  is open — readers (the resolver, doctor) only check for
  non-emptiness, so new init sites can introduce new tags without
  coordinating with this package.

  Known tags today:
    - project           (will replace 4.10 NeedsAIProjectProvision)
    - model_deployment  (fixes the user-reported bug in commit B)
    - acr               (covered in commit D)
    - app_insights      (covered in commit D)

  Lifecycle is explicit, unlike 4.10's USE_EXISTING_AI_PROJECT signal
  derivation: init sites append tags as they decide; postprovision
  clears the list. The resolver and doctor read the snapshot.

Components

  internal/cmd/pending_provision.go  (NEW, ~170 LoC)
    Helpers for parsing/formatting/reading/writing the env var:
      - parsePendingProvisionReasons(value)
      - formatPendingProvisionReasons(reasons)
      - addPendingProvisionReason(ctx, client, env, reason)
      - removePendingProvisionReason(ctx, client, env, reason)
      - clearPendingProvisionReasons(ctx, client, env)
      - readPendingProvisionEnv(ctx, client, env) — NotFound-tolerant
      - mutatePendingProvisionReasons(...)        — shared RMW core
    All write helpers are idempotent (skip the SetValue call when the
    formatted value equals the prior on-disk value). Best-effort
    parse normalization keeps the signal robust against hand edits.

  internal/cmd/pending_provision_test.go  (NEW)
    Full coverage: parse edge cases, format normalization, add to
    empty / append / duplicate-noop, remove existing / non-existent
    / from-unset, clear, and a round-trip sequence verifying
    parse/format consistency end-to-end. Uses the existing
    testEnvironmentServiceServer fixture pattern.

  internal/cmd/listen.go  (postprovisionHandler)
    After the toolbox-provision loop completes successfully, if any
    azure.ai.agent service was processed, fetch the current env name
    via Environment().GetCurrent and call
    clearPendingProvisionReasons. Best-effort: a transport failure
    is logged but not returned, since user's provision DID succeed
    and surfacing a clear-time error would be confusing. New helper
    currentEnvName() factors out the GetCurrent dance.

  internal/cmd/nextstep/state.go  (assembleState)
    Reads AI_AGENT_PENDING_PROVISION alongside the existing
    USE_EXISTING_AI_PROJECT read, parses into the new
    State.PendingProvisionReasons field via a local
    parsePendingProvisionReasons copy (nextstep is a leaf package;
    cannot import cmd). Transport errors increment errCount but do
    not abort assembly — the field is best-effort and the resolver
    tolerates an empty list.

  internal/cmd/nextstep/types.go
    New field State.PendingProvisionReasons with a doc comment
    describing the signal contract and pointing back at
    pending_provision.go for the canonical helpers.

  internal/cmd/nextstep/resolver.go  (ResolveAfterInit case 1)
    OR-in `len(state.PendingProvisionReasons) > 0` so any non-empty
    list fires the `azd provision` primary, regardless of whether
    NeedsAIProjectProvision is set or AZURE_AI_PROJECT_ENDPOINT is
    populated. Decision-tree doc comment updated. The legacy
    NeedsAIProjectProvision branch is retained for backwards
    compatibility — commit C will migrate init.go to write tags
    directly and the field will be removed at that point.

Tests

  Existing 4.10 sub-cases for NeedsAIProjectProvision stay green.
  Three new state_test.go sub-cases lock the new field's parse
  contract end-to-end (unset/single/multiple/malformed); the
  transport-error tests bump errCount 3→4 and 4→5 to account for
  the extra env read.

  Two new resolver_test.go sub-cases pin the override behavior:
  HasProjectEndpoint=true + PendingProvisionReasons non-empty must
  still suggest `azd provision`, with both single-tag and
  multi-tag inputs.

Pre-flight

  gofmt -s -w .            clean
  go vet ./...             clean
  go build ./...           clean
  go test ./...            green (cmd 13.9s, doctor 5.3s,
                                    nextstep 4.9s, agent_api 9.2s, etc.)
  golangci-lint run        0 issues
  cspell                   0 issues on changed production files

No behavior change yet — init.go, init_models.go, and
init_foundry_resources_helpers.go still drive their existing signals.
The resolver's case-1 condition is widened but no producer writes
PendingProvisionReasons in this commit; the empty list short-circuits
the OR, leaving identical behavior to 4.10.

Refs Azure#7975 (PR Azure#8057 design spec)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/cmd/listen.go

@@ -81,10 +81,12 @@ func postprovisionHandler(
 	azdClient *azdext.AzdClient,
 	args *azdext.ProjectEventArgs,
 ) error {
+	hasAgent := false
 	for _, svc := range args.Project.Services {
 		if svc.Host != AiAgentHost {
 			continue
 		}
+		hasAgent = true
 
 		if err := provisionToolboxes(ctx, azdClient, svc); err != nil {
 			return fmt.Errorf(
@@ -94,9 +96,64 @@ func postprovisionHandler(
 		}
 	}
 
+	// Clear the AI_AGENT_PENDING_PROVISION signal now that provision has
+	// finished successfully. Init writes resource-class tags into this
+	// variable when it configures non-existent infra (a new model
+	// deployment, a new Foundry project, a blank ACR/AppInsights input)
+	// so the post-init trailer and `azd ai agent doctor` can recommend
+	// `azd provision`. Once provision returns success the signal is
+	// stale: subsequent runs of doctor/init/run/show/deploy should rely
+	// on the canonical post-provision env vars (AZURE_AI_PROJECT_ENDPOINT
+	// and friends) and the agent.yaml-vs-env diff. The clear is gated on
+	// the presence of at least one azure.ai.agent service so toolbox-only
+	// or non-agent provisions don't write to a variable they don't own.
+	// Best-effort: a transport failure here is logged but not returned —
+	// the user's provision DID succeed and surfacing a clear-time error
+	// would be confusing. The next init/doctor run will simply re-emit
+	// the suggestion until the variable is cleared by a future
+	// successful provision (or by the user via `azd env set ... ""`).
+	if hasAgent {
+		envName, err := currentEnvName(ctx, azdClient)
+		switch {
+		case err != nil:
+			log.Printf(
+				"warning: failed to look up current environment to clear %s: %v",
+				pendingProvisionEnvVar, err,
+			)
+		case envName == "":
+			log.Printf(
+				"warning: no current environment selected; skipping clear of %s",
+				pendingProvisionEnvVar,
+			)
+		default:
+			if clearErr := clearPendingProvisionReasons(ctx, azdClient, envName); clearErr != nil {
+				log.Printf(
+					"warning: failed to clear %s after provision: %v",
+					pendingProvisionEnvVar, clearErr,
+				)
+			}
+		}
+	}
+
 	return nil
 }
 
+// currentEnvName returns the name of the currently selected azd
+// environment, or empty string + error when no environment is
+// selected. Wraps Environment().GetCurrent so callers (notably
+// postprovisionHandler) can read the current env name without
+// duplicating the request shape.
+func currentEnvName(ctx context.Context, azdClient *azdext.AzdClient) (string, error) {
+	resp, err := azdClient.Environment().GetCurrent(ctx, &azdext.EmptyRequest{})
+	if err != nil {
+		return "", err
+	}
+	if resp == nil || resp.Environment == nil {
+		return "", nil
+	}
+	return resp.Environment.Name, nil
+}
+
 func predeployHandler(ctx context.Context, azdClient *azdext.AzdClient, args *azdext.ProjectEventArgs) error {
 	hasHostedAgent := false
 	for _, svc := range args.Project.Services {

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver.go

@@ -40,8 +40,8 @@ const (
 //     are deploy-time landmines: the literal `{{NAME}}` would otherwise
 //     land in the container. They never reach `azd env set` because the
 //     value lives in agent.yaml itself, not the azd environment.
-//   - NeedsAIProjectProvision OR !HasProjectEndpoint OR MissingInfraVars
-//     → `azd provision`
+//   - NeedsAIProjectProvision OR len(PendingProvisionReasons) > 0 OR
+//     !HasProjectEndpoint OR MissingInfraVars → `azd provision`
 //     The project endpoint is the canonical "provision finished"
 //     marker — it is set by `azd provision` as a Bicep output, or by
 //     `azd ai agent init` when the user selects an existing Foundry
@@ -59,6 +59,11 @@ const (
 //     prior init or environment is stale and must not let the resolver
 //     mistake the state for "ready to run or deploy". See
 //     state.NeedsAIProjectProvision for the env-var contract.
+//     PendingProvisionReasons generalizes the same idea to any
+//     resource class — model deployments, ACR, App Insights, etc. —
+//     so this branch fires whenever init recorded *any* tag the
+//     postprovision handler has not yet cleared. See
+//     state.PendingProvisionReasons for the env-var contract.
 //   - MissingManualVars  → one `azd env set <KEY> <value>` per missing var
 //     (up to maxFixupLines)
 //   - Otherwise          → `azd ai agent run`
@@ -94,7 +99,10 @@ func ResolveAfterInit(state *State) []Suggestion {
 	}
 
 	switch {
-	case state.NeedsAIProjectProvision || !state.HasProjectEndpoint || len(state.MissingInfraVars) > 0:
+	case state.NeedsAIProjectProvision ||
+		len(state.PendingProvisionReasons) > 0 ||
+		!state.HasProjectEndpoint ||
+		len(state.MissingInfraVars) > 0:
 		out = append(out, Suggestion{
 			Command:     "azd provision",
 			Description: "set up your Foundry project, models, and connections",

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/resolver_test.go

@@ -91,6 +91,35 @@ func TestResolveAfterInit(t *testing.T) {
 			wantPrimaryHas: "azd ai agent run",
 			wantTrailing:   "azd deploy",
 		},
+		{
+			// Init configured a new model deployment in an existing
+			// Foundry project: HasProjectEndpoint=true (existing
+			// project), NeedsAIProjectProvision=false (existing
+			// project), but PendingProvisionReasons contains
+			// "model_deployment". The resolver must still suggest
+			// `azd provision` so Bicep creates the new deployment.
+			name: "new model deployment in existing project → provision (PendingProvisionReasons override)",
+			state: &State{
+				HasProjectEndpoint:      true,
+				NeedsAIProjectProvision: false,
+				PendingProvisionReasons: []string{"model_deployment"},
+			},
+			wantPrimaryHas: "azd provision",
+			wantTrailing:   "azd deploy",
+		},
+		{
+			// Multiple pending reasons collected during init —
+			// e.g. user left ACR blank and configured a new model.
+			// Still single `azd provision` suggestion (resolver
+			// treats the list as opaque non-emptiness).
+			name: "multiple pending reasons → single provision suggestion",
+			state: &State{
+				HasProjectEndpoint:      true,
+				PendingProvisionReasons: []string{"acr", "model_deployment"},
+			},
+			wantPrimaryHas: "azd provision",
+			wantTrailing:   "azd deploy",
+		},
 	}
 
 	for _, tt := range tests {

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/state.go

@@ -46,6 +46,16 @@ const (
 	// USE_EXISTING_AI_PROJECT in CHANGELOG.md entry for PR #7843.
 	useExistingAIProjectVar = "USE_EXISTING_AI_PROJECT"
 
+	// pendingProvisionVar names the extension-owned env var that
+	// lists resource-class tags init configured but provision has
+	// not yet materialized. See State.PendingProvisionReasons for
+	// the full semantics and pending_provision.go in the cmd package
+	// for the read/write helpers and the reason-tag taxonomy. The
+	// constant is duplicated here (rather than imported from cmd)
+	// because nextstep is a leaf package with no dependency on cmd
+	// — both packages share the same string literal contract.
+	pendingProvisionVar = "AI_AGENT_PENDING_PROVISION"
+
 	// azureInfraPrefix tags an env-var name as an azd-infra output rather
 	// than a user-supplied manual variable. Outputs of `azd provision`
 	// in the AI Foundry templates uniformly start with this prefix
@@ -243,6 +253,23 @@ func assembleState(ctx context.Context, src Source, opts ...Option) (*State, []e
 			errs = append(errs, fmt.Errorf("read %s: %w", useExistingAIProjectVar, err))
 		}
 		state.NeedsAIProjectProvision = useExisting == "false"
+
+		// PendingProvisionReasons is the generalized "init configured
+		// something provision still has to materialize" signal that
+		// the model-deployment / ACR / App-Insights blank-input
+		// branches write into. Read here so the resolver and doctor
+		// share one snapshot. Unknown tags are kept verbatim — the
+		// resolver only checks for non-emptiness, and downstream
+		// readers may interpret tags they recognize. Transport
+		// errors are surfaced into errs but do not abort assembly;
+		// the field is best-effort and the resolver tolerates an
+		// empty list (it falls back to legacy heuristics in that
+		// case).
+		pending, err := src.EnvValue(ctx, envName, pendingProvisionVar)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("read %s: %w", pendingProvisionVar, err))
+		}
+		state.PendingProvisionReasons = parsePendingProvisionReasons(pending)
 	}
 
 	project, err := src.Project(ctx)
@@ -526,3 +553,33 @@ func serviceKey(name string) string {
 	k = strings.ReplaceAll(k, "-", "_")
 	return strings.ToUpper(k)
 }
+
+// parsePendingProvisionReasons splits the AI_AGENT_PENDING_PROVISION
+// env-var value into a sorted, deduplicated, whitespace-trimmed list of
+// reason tags. Empty input or input containing only separators returns
+// nil. Malformed input is best-effort normalized — the env var is a
+// hint signal and parse trouble should not abort state assembly. This
+// helper mirrors cmd.parsePendingProvisionReasons; the duplication is
+// intentional to keep nextstep a leaf package with no dependency on cmd.
+func parsePendingProvisionReasons(value string) []string {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+	seen := make(map[string]struct{})
+	for _, raw := range strings.Split(value, ",") {
+		tag := strings.TrimSpace(raw)
+		if tag == "" {
+			continue
+		}
+		seen[tag] = struct{}{}
+	}
+	if len(seen) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(seen))
+	for tag := range seen {
+		out = append(out, tag)
+	}
+	slices.Sort(out)
+	return out
+}

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/state_test.go

@@ -156,10 +156,11 @@ func TestAssembleState(t *testing.T) {
 				assert.False(t, state.Services[0].IsDeployed)
 				assert.False(t, state.HasProjectEndpoint)
 				assert.False(t, state.NeedsAIProjectProvision)
+				assert.Empty(t, state.PendingProvisionReasons)
 			},
-			// One error for AZURE_AI_PROJECT_ENDPOINT + one for USE_EXISTING_AI_PROJECT
-			// + one per service lookup (AGENT_ECHO_VERSION) = 3.
-			errCount: 3,
+			// One error each for AZURE_AI_PROJECT_ENDPOINT, USE_EXISTING_AI_PROJECT,
+			// AI_AGENT_PENDING_PROVISION + one per service lookup (AGENT_ECHO_VERSION) = 4.
+			errCount: 4,
 		},
 		{
 			name: "USE_EXISTING_AI_PROJECT unset: NeedsAIProjectProvision stays false",
@@ -223,6 +224,59 @@ func TestAssembleState(t *testing.T) {
 				assert.False(t, state.NeedsAIProjectProvision)
 			},
 		},
+		{
+			name: "AI_AGENT_PENDING_PROVISION unset: PendingProvisionReasons stays empty",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values:  map[string]string{"dev/AZURE_AI_PROJECT_ENDPOINT": "https://x.services.ai.azure.com"},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.Empty(t, state.PendingProvisionReasons)
+			},
+		},
+		{
+			name: "AI_AGENT_PENDING_PROVISION single tag: PendingProvisionReasons populated",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					"dev/AZURE_AI_PROJECT_ENDPOINT":  "https://x.services.ai.azure.com",
+					"dev/AI_AGENT_PENDING_PROVISION": "model_deployment",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.Equal(t, []string{"model_deployment"}, state.PendingProvisionReasons)
+			},
+		},
+		{
+			name: "AI_AGENT_PENDING_PROVISION multiple tags: parsed sorted dedup",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					"dev/AZURE_AI_PROJECT_ENDPOINT":  "https://x.services.ai.azure.com",
+					"dev/AI_AGENT_PENDING_PROVISION": "project,acr,project,model_deployment",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.Equal(t, []string{"acr", "model_deployment", "project"}, state.PendingProvisionReasons)
+			},
+		},
+		{
+			name: "AI_AGENT_PENDING_PROVISION malformed value: best-effort normalize",
+			src: &fakeSource{
+				envName: "dev",
+				project: &azdext.ProjectConfig{Name: "demo"},
+				values: map[string]string{
+					"dev/AZURE_AI_PROJECT_ENDPOINT":  "https://x.services.ai.azure.com",
+					"dev/AI_AGENT_PENDING_PROVISION": "  ,, project ,, acr , ",
+				},
+			},
+			assert: func(t *testing.T, state *State, _ []error) {
+				assert.Equal(t, []string{"acr", "project"}, state.PendingProvisionReasons)
+			},
+		},
 	}
 
 	for _, tt := range tests {
@@ -899,8 +953,8 @@ environment_variables:
 
 	state, errs := assembleState(context.Background(), src)
 	// One error each for AZURE_AI_PROJECT_ENDPOINT + USE_EXISTING_AI_PROJECT
-	// + AGENT_ECHO_VERSION + MY_API_KEY.
-	assert.Len(t, errs, 4)
+	// + AI_AGENT_PENDING_PROVISION + AGENT_ECHO_VERSION + MY_API_KEY = 5.
+	assert.Len(t, errs, 5)
 	assert.Empty(t, state.MissingInfraVars)
 	assert.Empty(t, state.MissingManualVars)
 }

cli/azd/extensions/azure.ai.agents/internal/cmd/nextstep/types.go

@@ -80,8 +80,34 @@ type State struct {
 	// endpoint check independently passes. The flag is false when the
 	// variable is unset (no prior init) or "true" (existing path) so
 	// the existing heuristic continues to drive those cases.
+	//
+	// NOTE: Slated for removal in a follow-up commit (commit C) once
+	// init.go is migrated to call addPendingProvisionReason("project")
+	// directly. The replacement signal is PendingProvisionReasons
+	// below; both fields are read by the resolver in the interim so
+	// the migration can land in small, independently reviewable steps.
 	NeedsAIProjectProvision bool
 
+	// PendingProvisionReasons lists the resource-class tags that
+	// `azd ai agent init` configured but Azure has not yet
+	// materialized. Init code paths append a tag — e.g.
+	// "model_deployment" when a new model deployment is configured in
+	// an existing project, "project" when a new Foundry project is
+	// selected, "acr"/"app_insights" when the user leaves those
+	// inputs blank — and the postprovisionHandler clears the list on
+	// successful provision. The resolver fires `azd provision`
+	// whenever the list is non-empty; doctor can surface the specific
+	// reasons for richer diagnostics.
+	//
+	// The signal is stored in the AI_AGENT_PENDING_PROVISION env var
+	// (extension-owned namespace, not AZURE_*) as a comma-separated,
+	// sorted, deduplicated string. Unknown tags are tolerated by the
+	// resolver for forward-compatibility, so new init sites can
+	// introduce new tags without coordinating with this package. See
+	// pending_provision.go for the read/write helpers and the
+	// reason-tag taxonomy.
+	PendingProvisionReasons []string
+
 	// MissingInfraVars names ${...} references in agent.yaml that map to
 	// Bicep outputs not yet present in the azd environment (i.e.,
 	// provision is needed or has been skipped). Named so the resolver can