[azure.ai.agents] nextstep: surface every fix-up category after init/doctor, broaden placeholder regex

Two correctness fixes from the 3/3-consensus review of commit 4.6
(`2194327e8`). GPT-5.5 surfaced both initially; cross-pollination to
Opus 4.7 (xhigh) and Sonnet 4.6 confirmed both findings 3/3 — Sonnet
flipped its initial APPROVE after re-reading the renderer.

G1 (renderer): when ResolveAfterInit emits multiple fix-up categories
in a single state (e.g. the toolbox sample: 1 unresolved {{NAME}}
placeholder + 1 missing manual env var + the trailing `azd deploy`
reminder), PrintNext silently truncated the env-set line. PrintNext
caps total rendered lines at maxRendered=2 with one slot reserved for
the Trailing entry — so the budget for primaries is 1, and any
secondary category gets dropped on the floor. Pre-4.6 the toolbox
state was [env-set, deploy/trailing] → both rendered. Post-4.6 the
state became [placeholder, env-set, deploy/trailing] → only
[placeholder, deploy] rendered. Net effect: the user saw the
placeholder hint and the deploy reminder, but had no idea they also
needed to `azd env set TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT <value>`.
The 2-line cap exists for mid-flow resolvers (Run/Invoke/Show, all of
which produce ≤2 suggestions naturally — the cap prevents drowning
out subsequent command output). It does NOT apply to ResolveAfterInit
or doctor, both of which fire at the very END of their command with
no further output to drown. Fix: parameterize renderBlock with a
limit argument (0 = uncapped) and add a sibling `PrintAllNext`
that calls renderBlock(suggestions, 0). Switch init.go and
doctor_format.go to PrintAllNext. PrintNext semantics (and all its
existing tests) preserved byte-for-byte for the mid-flow callers
(invoke.go, run.go, show.go). Worst-case bound for the uncapped
renderer is 7 lines (3 placeholders + 3 manual vars + 1 trailing),
already capped at the resolver level by maxFixupLines=3 per category
in resolver.go.

G2 (regex): the placeholder-detection regex in state.go was
`\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}` — accepted only Go-style
identifier names. But parameters.go:237-244 substitutes the raw YAML
parameter name into the template via `fmt.Sprintf("{{%s}}", paramName)`
WITHOUT any shape validation, and yaml.go:425-431 assigns the raw
YAML key to Property.Name with no validation either. So a manifest
can legally use names like `toolbox-endpoint`, `my.component.id`, or
even quoted YAML keys containing whitespace — and 4.6's
placeholder-detection silently missed all of them. Broadened to
`\{\{\s*([^\s{}][^{}]*?)\s*\}\}` (first char must be non-whitespace
non-brace; remaining is lazy any-non-brace). Allows hyphens, dots,
and internal whitespace in paramName. Empty braces `{{}}` and
whitespace-only braces `{{   }}` correctly do NOT match (because the
first capture-group char must be non-whitespace non-brace). Picked
Sonnet's regex over Opus's `[^\s{}]+?` because Sonnet's is slightly
more permissive — covers the rare-but-valid quoted-YAML-key-with-
whitespace case. Trade-off: tiny false-positive risk (the surfaced
suggestion is benign — just an "edit agent.yaml" line — and false
negatives are the bug we're fixing, so we err toward detection).

The toolbox-sample regression is locked at two layers:
- format_test.go: a hand-crafted Suggestions slice matching the
  exact toolbox state ("G1 regression repro" sub-case).
- resolver_test.go: a new end-to-end test that builds the State,
  runs it through ResolveAfterInit, renders with PrintAllNext, and
  asserts all three lines (placeholder, env-set, deploy) appear.
- state_test.go: extended the placeholder-extraction table with
  hyphenated, dotted, empty-braces, and whitespace-only-braces cases.
- format_test.go: new TestPrintAllNext / TestPrintAllNext_Propagates
  WriteError / TestPrintAllNext_EmptyInputSkipsWrite covering
  empty input, single-suggestion, the G1 toolbox shape, worst-case
  7-line uncapped render, and the trailing-last invariant under
  uncapped mode.

Files: 7 changed.
- format.go: renderBlock(suggestions) → renderBlock(suggestions,
  limit). New PrintAllNext(w, suggestions). PrintNext doc-comment
  points at PrintAllNext for multi-category flows.
- state.go: placeholderPattern broadened. Doc comment cites the
  YAML key examples (toolbox-endpoint, my.param, "my key") and
  links to parameters.go's substitution code.
- init.go:1608, doctor_format.go:116: PrintNext → PrintAllNext.
  doctor_format.go's surrounding doc-comment updated to mention
  PrintAllNext rationale.
- format_test.go, state_test.go, resolver_test.go: tests as above.

Pre-flight: gofmt clean, vet clean, build clean, full extension
test suite green (cmd 17.2s, nextstep 5.8s, doctor 5.8s, agent_api
9.1s, agent_yaml 2.1s, etc.), golangci-lint 0 issues on
./internal/cmd/nextstep/... + ./internal/cmd/..., cspell 0 issues
on the 4 production files. The existing TestPrintNext suite
(including "more than two suggestions are truncated by priority"
and "trailing suggestion survives truncation when primaries fill
the block") still passes — PrintNext is unchanged.

Refs PR Azure#8057 (azd ai agent context-aware next-step guidance).
Consensus tally: G1 = GPT-5.5 (MEDIUM) + Sonnet (High, flipped) +
Opus (Medium, acknowledged miss) = 3/3. G2 = GPT-5.5 (Low) +
Sonnet (Low) + Opus (Low) = 3/3.

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

Author: Antriksh Jain

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

@@ -86,9 +86,12 @@ func printDoctorReportJSON(w io.Writer, report doctor.Report) error {
 // Summary line is appended after the per-check block.
 //
 // The trailing Next: block is rendered only when showNext is true.
-// nextstep.PrintNext owns the leading blank-line separator (see
+// nextstep.PrintAllNext owns the leading blank-line separator (see
 // nextstep/format.go renderBlock), so this function does not pre-emit
-// one.
+// one. PrintAllNext (not PrintNext) is used because doctor surfaces
+// the same multi-category fix-up list as `azd ai agent init` — every
+// line is a required action, and silently dropping any of them would
+// hide work the user still has to do.
 func printDoctorReportText(
 	w io.Writer,
 	report doctor.Report,
@@ -113,7 +116,7 @@ func printDoctorReportText(
 	}
 
 	if showNext {
-		if err := nextstep.PrintNext(w, trailing); err != nil {
+		if err := nextstep.PrintAllNext(w, trailing); err != nil {
 			return err
 		}
 	}

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

@@ -2017,7 +2017,7 @@ func (a *InitAction) addToProject(ctx context.Context, targetDir string, agentMa
 	// trailing line. State-assembly errors are intentionally ignored: the
 	// resolver degrades gracefully on partial state per the design spec.
 	state, _ := nextstep.AssembleState(ctx, a.azdClient)
-	_ = nextstep.PrintNext(os.Stdout, nextstep.ResolveAfterInit(state))
+	_ = nextstep.PrintAllNext(os.Stdout, nextstep.ResolveAfterInit(state))
 	return nil
 }
 

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

@@ -31,8 +31,34 @@ const (
 // PrintNext does not inspect TTY state or output-format flags — those
 // decisions live at the call site so the same renderer can serve both
 // interactive stdout writes and string capture for tests / JSON envelopes.
+//
+// Use PrintAllNext when the resolver produces multiple REQUIRED follow-up
+// actions (init / doctor fix-ups) where silently dropping any of them
+// would mislead the user.
 func PrintNext(w io.Writer, suggestions []Suggestion) error {
-	block := renderBlock(suggestions)
+	block := renderBlock(suggestions, maxRendered)
+	if block == "" {
+		return nil
+	}
+	_, err := io.WriteString(w, block)
+	return err
+}
+
+// PrintAllNext writes a "Next:" guidance block to w like PrintNext but
+// renders every suggestion (no two-line cap). Use this for flows where
+// the suggestions are all REQUIRED follow-up actions rather than
+// alternatives — the post-init flow can surface unresolved manifest
+// placeholders, missing `azd env set` keys, AND the trailing
+// `azd deploy` reminder simultaneously, and the user has to act on each
+// one. Dropping any of them silently leaves the user thinking they are
+// ready to deploy when they are not.
+//
+// Suggestions are still stable-sorted by Priority (ties preserve input
+// order), the Trailing entry is still rendered last, and framing
+// (leading blank line + trailing newline) matches PrintNext. Empty
+// input is a no-op.
+func PrintAllNext(w io.Writer, suggestions []Suggestion) error {
+	block := renderBlock(suggestions, 0)
 	if block == "" {
 		return nil
 	}
@@ -65,9 +91,11 @@ func FormatNextForNote(suggestions []Suggestion) string {
 
 // renderBlock returns the formatted "Next:" block (with a leading blank
 // line and trailing newline) or an empty string when there is nothing to
-// render. The block is capped at maxRendered visible lines.
-func renderBlock(suggestions []Suggestion) string {
-	body := renderRows(suggestions, maxRendered)
+// render. limit is forwarded to renderRows: a positive value caps the
+// block at that many visible lines (PrintNext default), while limit <= 0
+// renders every suggestion (PrintAllNext).
+func renderBlock(suggestions []Suggestion, limit int) string {
+	body := renderRows(suggestions, limit)
 	if body == "" {
 		return ""
 	}

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

@@ -144,6 +144,116 @@ func TestPrintNext_EmptyInputSkipsWrite(t *testing.T) {
 	require.NoError(t, PrintNext(failingWriter{}, nil))
 }
 
+func TestPrintAllNext(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		suggestions []Suggestion
+		want        string
+	}{
+		{
+			name:        "empty input produces no output",
+			suggestions: nil,
+			want:        "",
+		},
+		{
+			name: "single suggestion renders identically to PrintNext",
+			suggestions: []Suggestion{
+				{Command: "azd provision", Description: "set up Foundry"},
+			},
+			want: "\nNext:  azd provision  -- set up Foundry\n",
+		},
+		{
+			name: "G1 regression repro: placeholder + manual var + trailing deploy all render (no cap)",
+			// This is the toolbox-sample state that motivated commit 2194327e8.
+			// PrintNext (capped at 2 with trailing reservation) would render
+			// only [placeholder, deploy] and drop the env-set line, leaving
+			// the user thinking they only need to fix the placeholder before
+			// deploying. PrintAllNext must surface all three.
+			suggestions: []Suggestion{
+				{
+					Command:     "edit agent.yaml: replace {{TOOLBOX_ENDPOINT}} with the actual value",
+					Description: "agent.yaml has unresolved manifest placeholders",
+					Priority:    5,
+				},
+				{
+					Command:     "azd env set TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT <value>",
+					Description: "supply the agent.yaml variable",
+					Priority:    6,
+				},
+				{
+					Command:     "azd deploy",
+					Description: "when ready to deploy to Azure",
+					Priority:    90,
+					Trailing:    true,
+				},
+			},
+			want: "\n" +
+				"Next:  edit agent.yaml: replace {{TOOLBOX_ENDPOINT}} with the actual value  -- agent.yaml has unresolved manifest placeholders\n" +
+				"       azd env set TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT <value>            -- supply the agent.yaml variable\n" +
+				"       azd deploy                                                           -- when ready to deploy to Azure\n",
+		},
+		{
+			name: "renders well beyond maxRendered (3 placeholders + 3 manual vars + trailing = 7 lines)",
+			// Worst-case shape from ResolveAfterInit when both
+			// maxFixupLines caps are saturated.
+			suggestions: []Suggestion{
+				{Command: "edit agent.yaml: replace {{A}} with the actual value", Description: "p1", Priority: 5},
+				{Command: "edit agent.yaml: replace {{B}} with the actual value", Description: "p1", Priority: 6},
+				{Command: "edit agent.yaml: replace {{C}} with the actual value", Description: "p1", Priority: 7},
+				{Command: "azd env set FOO <value>", Description: "p2", Priority: 8},
+				{Command: "azd env set BAR <value>", Description: "p2", Priority: 9},
+				{Command: "azd env set BAZ <value>", Description: "p2", Priority: 10},
+				{Command: "azd deploy", Description: "p3", Priority: 90, Trailing: true},
+			},
+			want: "\n" +
+				"Next:  edit agent.yaml: replace {{A}} with the actual value  -- p1\n" +
+				"       edit agent.yaml: replace {{B}} with the actual value  -- p1\n" +
+				"       edit agent.yaml: replace {{C}} with the actual value  -- p1\n" +
+				"       azd env set FOO <value>                               -- p2\n" +
+				"       azd env set BAR <value>                               -- p2\n" +
+				"       azd env set BAZ <value>                               -- p2\n" +
+				"       azd deploy                                            -- p3\n",
+		},
+		{
+			name: "trailing entry still rendered last regardless of input order",
+			suggestions: []Suggestion{
+				{Command: "azd deploy", Description: "when ready", Priority: 90, Trailing: true},
+				{Command: "first", Description: "f", Priority: 5},
+				{Command: "second", Description: "s", Priority: 6},
+			},
+			want: "\n" +
+				"Next:  first       -- f\n" +
+				"       second      -- s\n" +
+				"       azd deploy  -- when ready\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var buf bytes.Buffer
+			require.NoError(t, PrintAllNext(&buf, tt.suggestions))
+			assert.Equal(t, tt.want, buf.String())
+		})
+	}
+}
+
+func TestPrintAllNext_PropagatesWriteError(t *testing.T) {
+	t.Parallel()
+
+	err := PrintAllNext(failingWriter{}, []Suggestion{{Command: "x", Description: "y"}})
+	require.ErrorIs(t, err, io.ErrUnexpectedEOF)
+}
+
+func TestPrintAllNext_EmptyInputSkipsWrite(t *testing.T) {
+	t.Parallel()
+
+	require.NoError(t, PrintAllNext(failingWriter{}, nil))
+}
+
 func TestFormatNextForNote(t *testing.T) {
 	t.Parallel()
 

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

@@ -107,6 +107,35 @@ func TestResolveAfterInit_NilState(t *testing.T) {
 	assert.Nil(t, ResolveAfterInit(nil))
 }
 
+// TestResolveAfterInit_ToolboxReproRendersAllCategories locks the full
+// regression for the toolbox-sample bug end-to-end: the state contains
+// BOTH an unresolved manifest placeholder AND a missing manual env var,
+// and the rendered "Next:" block must surface both fix-up categories
+// plus the trailing `azd deploy` reminder. PrintNext would silently
+// drop one category here because of its 2-line cap; PrintAllNext must
+// not.
+func TestResolveAfterInit_ToolboxReproRendersAllCategories(t *testing.T) {
+	t.Parallel()
+
+	state := &State{
+		HasProjectEndpoint:     true,
+		UnresolvedPlaceholders: []string{"TOOLBOX_ENDPOINT"},
+		MissingManualVars:      []string{"TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT"},
+	}
+
+	var buf strings.Builder
+	require.NoError(t, PrintAllNext(&buf, ResolveAfterInit(state)))
+	rendered := buf.String()
+
+	assert.Contains(t, rendered,
+		"edit agent.yaml: replace {{TOOLBOX_ENDPOINT}} with the actual value",
+		"placeholder fix-up missing")
+	assert.Contains(t, rendered,
+		"azd env set TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT <value>",
+		"manual-var fix-up missing — this is the original toolbox-sample regression")
+	assert.Contains(t, rendered, "azd deploy", "trailing deploy reminder missing")
+}
+
 func TestResolveAfterInit_UnresolvedPlaceholders(t *testing.T) {
 	t.Parallel()
 

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

@@ -62,10 +62,18 @@ var envVarRefPattern = regexp.MustCompile(`\$\{([A-Za-z_][A-Za-z0-9_]*)(:-[^}]*)
 // environment_variables values are deploy-time landmines: the value will
 // land in the container literally as `{{NAME}}`, breaking the agent.
 //
-// Allows optional internal whitespace (`{{ NAME }}`) because parameters.go
-// substitutes both forms. Names follow the same convention as env vars
-// (leading letter or underscore, then alphanumeric or underscore).
-var placeholderPattern = regexp.MustCompile(`\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}`)
+// The capture group accepts any run of non-brace characters (allowing
+// internal whitespace as long as the name starts with a non-whitespace,
+// non-brace char) because parameters.go substitutes the raw manifest
+// parameter key without validating its shape (`strings.ReplaceAll` of
+// `{{<paramName>}}` and `{{ <paramName> }}`). A legitimate manifest
+// parameter named `toolbox-endpoint` (hyphen), `my.param` (dot), or
+// even `"my key"` (quoted YAML key with whitespace) would otherwise
+// slip past detection. Allows optional surrounding whitespace inside
+// the braces — matches both `{{NAME}}` and `{{ NAME }}` (the two
+// forms parameters.go knows how to substitute) plus more liberal
+// spacing for forgiving detection.
+var placeholderPattern = regexp.MustCompile(`\{\{\s*([^\s{}][^{}]*?)\s*\}\}`)
 
 // Source is the read-only view of azd that AssembleState needs.
 //

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

@@ -571,6 +571,52 @@ environment_variables:
 			wantRefs:         []string{"TOOLBOX_WEB_SEARCH_TOOLS_MCP_ENDPOINT"},
 			wantPlaceholders: []string{"TOOLBOX_ENDPOINT"},
 		},
+		{
+			// Manifest parameter names are not constrained to env-var
+			// identifier shape — parameters.go:injectParameterValues
+			// substitutes the raw YAML key without validating it.
+			// A surviving `{{toolbox-endpoint}}` (hyphen) must therefore
+			// still be flagged or the user gets no Next: hint.
+			name: "mustache placeholder with hyphen in name",
+			manifest: `kind: hostedAgent
+environment_variables:
+  - name: TOOLBOX_ENDPOINT
+    value: '{{toolbox-endpoint}}'
+`,
+			wantPlaceholders: []string{"toolbox-endpoint"},
+		},
+		{
+			name: "mustache placeholder with dot in name",
+			manifest: `kind: hostedAgent
+environment_variables:
+  - name: COMPONENT
+    value: '{{my.component.id}}'
+`,
+			wantPlaceholders: []string{"my.component.id"},
+		},
+		{
+			// Empty placeholder body must not be flagged — it cannot
+			// correspond to a manifest parameter and is more likely
+			// stray literal text.
+			name: "empty mustache braces are ignored",
+			manifest: `kind: hostedAgent
+environment_variables:
+  - name: NOISE
+    value: 'preamble {{}} suffix'
+`,
+			wantPlaceholders: nil,
+		},
+		{
+			// Whitespace-only placeholder body is similarly garbage —
+			// must not be flagged.
+			name: "whitespace-only mustache braces are ignored",
+			manifest: `kind: hostedAgent
+environment_variables:
+  - name: NOISE
+    value: 'preamble {{   }} suffix'
+`,
+			wantPlaceholders: nil,
+		},
 	}
 
 	for _, tt := range tests {