feat(azure.ai.agents): add FormatNextForNote renderer for artifact embeds

Phase 3 foundation. Adds a string-returning sibling to PrintNext suitable
for embedding a Next: block inside an artifact's Metadata["note"]. No
production caller yet; the deploy-hook wire-up lands in commit 3.2.

Shape decisions:

* No truncation. The artifact note is a contained region (not interleaved
  with command output), so it should surface every suggestion. PrintNext's
  maxRendered=2 cap remains in force for the interactive stdout case.
* No leading or trailing newline. The artifact renderer prepends its own
  line break; an embedded "\n...\n" would double-space the output.
* Lines 2+ are pre-indented by 4 spaces so the command column stays
  aligned with line 1 when core azd's artifact renderer
  (cli/azd/pkg/project/artifact.go:128-130) is called with the typical
  caller indent of two spaces. The renderer indents line 1 of the note
  but lines 2+ are flush-left; pre-indenting compensates.

Strategy delta D21 — drop currentIndentation from the API. The plan's
signature took currentIndentation as a parameter, but the extension
cannot know what value core azd's renderer will pass at display time
(callers above us choose the indent). Hard-coding 4 spaces matches the
two-space caller indent used everywhere in the existing tree. Under
deeper or shallower caller indents the lines drift slightly but the
note remains readable.

Refactor: extracted renderRows(suggestions, limit) from renderBlock so
PrintNext (limit=maxRendered) and FormatNextForNote (limit=0, no cap)
share the partition-then-render core. Renamed the local variable away
from the Go builtin cap. Behavior of renderBlock / PrintNext is
unchanged — verified by the existing 7 TestPrintNext subtests.

Tests added in format_test.go:
- empty input returns ""
- single suggestion: no leading or trailing newline
- multi-line: line 2 pre-indented by 4 spaces
- uncapped: third suggestion preserved (would be dropped by PrintNext)
- trailing entry survives ordering
- TestFormatNextForNote_HostArtifactAlignment: round-trips a synthetic
  artifact render to lock the column-alignment contract

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

Author: Antriksh Jain

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

@@ -40,17 +40,53 @@ func PrintNext(w io.Writer, suggestions []Suggestion) error {
 	return err
 }
 
+// FormatNextForNote renders a "Next:" block as a string suitable for
+// embedding in an artifact's Metadata["note"]. Unlike PrintNext it does
+// not truncate the block (the artifact note is a contained region, not
+// interleaved with command output) and does not include a leading or
+// trailing newline (the artifact renderer adds its own line break).
+//
+// Lines 2+ are pre-indented by 4 spaces so the command column stays
+// aligned with line 1 when core azd's artifact renderer (which only
+// indents the first line of the note) is called with the typical caller
+// indent of two spaces — see cli/azd/pkg/project/artifact.go, which
+// writes "\n%s  %s" with the caller's indent on line 1 only. Under
+// deeper or shallower caller indents the lines drift slightly but the
+// note remains readable in both cases.
+//
+// Empty input returns an empty string.
+func FormatNextForNote(suggestions []Suggestion) string {
+	body := renderRows(suggestions, 0)
+	if body == "" {
+		return ""
+	}
+	return strings.ReplaceAll(strings.TrimSuffix(body, "\n"), "\n", "\n    ")
+}
+
 // renderBlock returns the formatted "Next:" block (with a leading blank
 // line and trailing newline) or an empty string when there is nothing to
-// render.
+// render. The block is capped at maxRendered visible lines.
+func renderBlock(suggestions []Suggestion) string {
+	body := renderRows(suggestions, maxRendered)
+	if body == "" {
+		return ""
+	}
+	// Leading blank line separates the block from preceding output.
+	return "\n" + body
+}
+
+// renderRows returns the formatted suggestion lines (one per line,
+// terminated with "\n") with no leading blank line. limit caps the
+// number of visible suggestions; limit <= 0 means render every
+// suggestion.
 //
 // Truncation is partitioned: at most one Suggestion.Trailing entry is
 // reserved for the final visible slot, with remaining slots filled by
 // primary (non-trailing) entries in ascending Priority order. The
 // trailing reservation lets resolvers emit follow-up nudges (e.g., the
 // post-action `azd deploy` line) without having those nudges silently
-// dropped when primary suggestions outnumber maxRendered.
-func renderBlock(suggestions []Suggestion) string {
+// dropped when primary suggestions outnumber the cap.
+func renderRows(suggestions []Suggestion, limit int) string {
 	if len(suggestions) == 0 {
 		return ""
 	}
@@ -76,20 +112,25 @@ func renderBlock(suggestions []Suggestion) string {
 	}
 
 	var rendered []Suggestion
-	if trailing != nil {
-		budget := maxRendered - 1
+	if limit > 0 && trailing != nil {
+		budget := limit - 1
 		if budget < 0 {
 			budget = 0
 		}
 		if len(primary) > budget {
 			primary = primary[:budget]
 		}
 		rendered = append(primary, *trailing)
-	} else {
-		if len(primary) > maxRendered {
-			primary = primary[:maxRendered]
+	} else if limit > 0 {
+		if len(primary) > limit {
+			primary = primary[:limit]
 		}
 		rendered = primary
+	} else {
+		rendered = primary
+		if trailing != nil {
+			rendered = append(rendered, *trailing)
+		}
 	}
 
 	if len(rendered) == 0 {
@@ -104,8 +145,6 @@ func renderBlock(suggestions []Suggestion) string {
 	}
 
 	var b strings.Builder
-	// Leading blank line separates the block from preceding output.
-	b.WriteByte('\n')
 	for i, s := range rendered {
 		if i == 0 {
 			b.WriteString(primaryPrefix)

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

@@ -143,3 +143,97 @@ func TestPrintNext_EmptyInputSkipsWrite(t *testing.T) {
 	// must short-circuit before any write.
 	require.NoError(t, PrintNext(failingWriter{}, nil))
 }
+
+func TestFormatNextForNote(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		suggestions []Suggestion
+		want        string
+	}{
+		{
+			name:        "empty input produces empty string",
+			suggestions: nil,
+			want:        "",
+		},
+		{
+			name: "single suggestion has no leading newline and no trailing newline",
+			suggestions: []Suggestion{
+				{Command: "azd ai agent invoke 'hello'", Description: "send a test request", Priority: 10},
+			},
+			want: "Next:  azd ai agent invoke 'hello'  -- send a test request",
+		},
+		{
+			name: "multi-line block pre-indents lines 2+ with 4 spaces",
+			suggestions: []Suggestion{
+				{Command: "azd ai agent show", Description: "verify deployment", Priority: 10},
+				{Command: "azd ai agent invoke 'hi'", Description: "send a request", Priority: 11},
+			},
+			want: "Next:  azd ai agent show         -- verify deployment\n" +
+				"           azd ai agent invoke 'hi'  -- send a request",
+		},
+		{
+			name: "uncapped — third suggestion is preserved (unlike PrintNext)",
+			suggestions: []Suggestion{
+				{Command: "azd ai agent show", Description: "verify deployment", Priority: 10},
+				{Command: "azd ai agent invoke 'hi'", Description: "send a request", Priority: 11},
+				{Command: "see ./agent/README.md", Description: "more sample requests", Priority: 12},
+			},
+			want: "Next:  azd ai agent show         -- verify deployment\n" +
+				"           azd ai agent invoke 'hi'  -- send a request\n" +
+				"           see ./agent/README.md     -- more sample requests",
+		},
+		{
+			name: "trailing entry surfaces even when not the lowest priority",
+			suggestions: []Suggestion{
+				{Command: "azd ai agent show", Description: "verify deployment", Priority: 10},
+				{Command: "azd deploy", Description: "redeploy after changes", Priority: 90, Trailing: true},
+				{Command: "azd ai agent invoke 'hi'", Description: "send a request", Priority: 11},
+			},
+			want: "Next:  azd ai agent show         -- verify deployment\n" +
+				"           azd ai agent invoke 'hi'  -- send a request\n" +
+				"           azd deploy                -- redeploy after changes",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			got := FormatNextForNote(tc.suggestions)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+// TestFormatNextForNote_HostArtifactAlignment verifies the 4-space
+// pre-indent matches the alignment core azd's artifact renderer produces
+// when called with the typical caller indent (currentIndentation == "  ").
+// Core azd's artifact.go writes the note as:
+//
+//	{indent}- {label}: ...
+//	{indent}  {note}             <- only line 1 of the note gets the
+//	                                indent+"  " prefix; lines 2+ are
+//	                                flush-left in the output stream.
+//
+// FormatNextForNote pre-indents lines 2+ by 4 spaces, which equals
+// indent("  ") + "  " — i.e. the columns align so the rendered "Next:"
+// header on line 1 sits directly above the continuation indent on line 2.
+func TestFormatNextForNote_HostArtifactAlignment(t *testing.T) {
+	t.Parallel()
+
+	note := FormatNextForNote([]Suggestion{
+		{Command: "azd ai agent show", Description: "verify deployment", Priority: 10},
+		{Command: "azd ai agent invoke 'hi'", Description: "send a request", Priority: 11},
+	})
+
+	// Simulate core azd's render: "  - label: location\n  " + note + "\n".
+	const callerIndent = "  "
+	rendered := callerIndent + "- endpoint: https://example/agents/foo/endpoint\n" +
+		callerIndent + "  " + note + "\n"
+
+	want := "  - endpoint: https://example/agents/foo/endpoint\n" +
+		"    Next:  azd ai agent show         -- verify deployment\n" +
+		"           azd ai agent invoke 'hi'  -- send a request\n"
+	assert.Equal(t, want, rendered)
+}