feat(azure.ai.agents): scaffold nextstep package and isTerminal helper

Add the foundation for context-aware `Next:` guidance described in PR Azure#8057:

- New `internal/cmd/nextstep` package with `Suggestion`, `State`, `ServiceState`, `AuthState` types and a format-agnostic `PrintNext` writer that aligns commands on the longest entry and caps output at one primary + one secondary line.

- Add an `isTerminal(fd uintptr) bool` helper in `internal/cmd/helpers.go` wrapping `golang.org/x/term`; promote that module from indirect to direct in `go.mod`.

- Register `nextstep` in the repo cspell dictionary.

No callers yet; resolvers, state assembly, and command wiring land in subsequent commits.

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

Author: Antriksh Jain

cli/azd/.vscode/cspell.yaml

@@ -42,6 +42,7 @@ words:
   - opencode
   - grpcbroker
   - msiexec
+  - nextstep
   - nosec
   - npx
   - oneof

cli/azd/extensions/azure.ai.agents/go.mod

@@ -28,6 +28,8 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 )
 
+require golang.org/x/term v0.41.0
+
 require (
 	dario.cat/mergo v1.0.2 // indirect
 	github.com/AlecAivazis/survey/v2 v2.3.7 // indirect
@@ -107,7 +109,6 @@ require (
 	golang.org/x/exp v0.0.0-20260112195511-716be5621a96 // indirect
 	golang.org/x/net v0.52.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 )

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

@@ -25,6 +25,7 @@ import (
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
 	"github.com/google/uuid"
 	"go.yaml.in/yaml/v3"
+	"golang.org/x/term"
 )
 
 const (
@@ -835,3 +836,10 @@ func multiProtocolError(
 		),
 	)
 }
+
+// isTerminal reports whether fd refers to an interactive terminal.
+// Used to gate human-only output such as the next-step guidance block.
+func isTerminal(fd uintptr) bool {
+	//nolint:gosec // file descriptors fit in int on all supported platforms
+	return term.IsTerminal(int(fd))
+}

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

@@ -299,3 +299,20 @@ func TestProtocolFromAgentYaml(t *testing.T) {
 		})
 	}
 }
+
+func TestIsTerminal_NonTTY(t *testing.T) {
+	t.Parallel()
+
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("os.Pipe: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = r.Close()
+		_ = w.Close()
+	})
+
+	if isTerminal(r.Fd()) {
+		t.Errorf("isTerminal(pipe read end) = true, want false")
+	}
+}

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

@@ -0,0 +1,84 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package nextstep
+
+import (
+	"io"
+	"slices"
+	"strings"
+)
+
+const (
+	// primaryPrefix is the leading label of the first suggestion line.
+	primaryPrefix = "Next:  "
+	// continuationPrefix indents subsequent lines so commands align under
+	// the first command. Width == len(primaryPrefix).
+	continuationPrefix = "       "
+	// commandSeparator separates the (possibly padded) command from its
+	// description. Two-space gap + "-- " per the design spec.
+	commandSeparator = "  -- "
+	// maxRendered caps the block at one primary + one optional secondary
+	// line ("more than two lines drowns out command output").
+	maxRendered = 2
+)
+
+// PrintNext writes a "Next:" guidance block to w. Suggestions are sorted
+// ascending by Priority (stable; ties preserve input order) and then
+// truncated to a primary + optional secondary line. Empty input produces
+// no output and no write.
+//
+// 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.
+func PrintNext(w io.Writer, suggestions []Suggestion) error {
+	block := renderBlock(suggestions)
+	if block == "" {
+		return nil
+	}
+	_, err := io.WriteString(w, block)
+	return err
+}
+
+// renderBlock returns the formatted "Next:" block (with a leading blank
+// line and trailing newline) or an empty string when there is nothing to
+// render.
+func renderBlock(suggestions []Suggestion) string {
+	if len(suggestions) == 0 {
+		return ""
+	}
+
+	sorted := slices.Clone(suggestions)
+	slices.SortStableFunc(sorted, func(a, b Suggestion) int {
+		return a.Priority - b.Priority
+	})
+	if len(sorted) > maxRendered {
+		sorted = sorted[:maxRendered]
+	}
+
+	cmdWidth := 0
+	for _, s := range sorted {
+		if n := len(s.Command); n > cmdWidth {
+			cmdWidth = n
+		}
+	}
+
+	var b strings.Builder
+	// Leading blank line separates the block from preceding output.
+	b.WriteByte('\n')
+	for i, s := range sorted {
+		if i == 0 {
+			b.WriteString(primaryPrefix)
+		} else {
+			b.WriteString(continuationPrefix)
+		}
+		b.WriteString(s.Command)
+		if pad := cmdWidth - len(s.Command); pad > 0 {
+			b.WriteString(strings.Repeat(" ", pad))
+		}
+		b.WriteString(commandSeparator)
+		b.WriteString(s.Description)
+		b.WriteByte('\n')
+	}
+	return b.String()
+}

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

@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package nextstep
+
+import (
+	"bytes"
+	"io"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPrintNext(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 one line with two-space gap",
+			suggestions: []Suggestion{
+				{Command: "azd provision", Description: "set up Foundry"},
+			},
+			want: "\nNext:  azd provision  -- set up Foundry\n",
+		},
+		{
+			name: "two suggestions align on longest command",
+			// Longest command "azd ai agent invoke 'hi'" is 24 chars.
+			// "azd ai agent show echo" (22) pads with 2 trailing spaces, then the
+			// two-space separator + "-- " (commandSeparator = "  -- ") so the gap
+			// between "echo" and "--" totals 4 spaces; the second line has no pad
+			// so its gap is exactly the 2-space separator.
+			suggestions: []Suggestion{
+				{Command: "azd ai agent show echo", Description: "verify status"},
+				{Command: "azd ai agent invoke 'hi'", Description: "test it"},
+			},
+			want: "\n" +
+				"Next:  azd ai agent show echo    -- verify status\n" +
+				"       azd ai agent invoke 'hi'  -- test it\n",
+		},
+		{
+			name: "more than two suggestions are truncated by priority",
+			suggestions: []Suggestion{
+				{Command: "c", Description: "third", Priority: 30},
+				{Command: "a", Description: "first", Priority: 10},
+				{Command: "b", Description: "second", Priority: 20},
+			},
+			want: "\n" +
+				"Next:  a  -- first\n" +
+				"       b  -- second\n",
+		},
+		{
+			name: "stable sort preserves input order on equal priorities",
+			suggestions: []Suggestion{
+				{Command: "first", Description: "f"},
+				{Command: "second", Description: "s"},
+			},
+			want: "\n" +
+				"Next:  first   -- f\n" +
+				"       second  -- s\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var buf bytes.Buffer
+			require.NoError(t, PrintNext(&buf, tt.suggestions))
+			assert.Equal(t, tt.want, buf.String())
+		})
+	}
+}
+
+// failingWriter returns an error on first Write; used to verify PrintNext
+// propagates I/O errors from the underlying writer.
+type failingWriter struct{}
+
+func (failingWriter) Write(_ []byte) (int, error) {
+	return 0, io.ErrUnexpectedEOF
+}
+
+func TestPrintNext_PropagatesWriteError(t *testing.T) {
+	t.Parallel()
+
+	err := PrintNext(failingWriter{}, []Suggestion{{Command: "x", Description: "y"}})
+	require.ErrorIs(t, err, io.ErrUnexpectedEOF)
+}
+
+func TestPrintNext_EmptyInputSkipsWrite(t *testing.T) {
+	t.Parallel()
+
+	// failingWriter would error if Write were called; nil suggestions
+	// must short-circuit before any write.
+	require.NoError(t, PrintNext(failingWriter{}, nil))
+}

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

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+// Package nextstep computes and renders the context-aware "Next:" guidance
+// block that azure.ai.agents commands surface at the end of successful (and
+// some failing) runs.
+//
+// The package is split into three concerns:
+//
+//   - State assembly (state.go) — collects everything resolvers may need
+//     into a single immutable snapshot; partial state never silences
+//     guidance.
+//   - Resolvers (resolver.go) — pure functions over *State that return a
+//     ranked []Suggestion for each command's exit path.
+//   - Formatters (format.go) — render []Suggestion either to a writer
+//     (PrintNext) or as a string suitable for embedding in an artifact's
+//     Metadata["note"] (FormatNextForNote).
+//
+// Output discipline lives at the call sites: the package never writes to
+// os.Stdout directly and never inspects --output flags. Callers gate on
+// the isTerminal helper / output mode and choose the writer or JSON
+// envelope field accordingly.
+package nextstep
+
+// Suggestion is a single line of next-step guidance: a command to run plus
+// a one-line description. Suggestions are sorted ascending by Priority
+// before rendering (lower = earlier; ties preserve input order).
+type Suggestion struct {
+	Command     string
+	Description string
+	Priority    int
+}
+
+// AuthState captures whether a doctor-style auth probe has been run and
+// what it found. AuthUnknown (the zero value) means the probe was not run;
+// resolvers treat that as "skip auth-conditional advice" rather than
+// emitting login-prompt noise on every successful command.
+type AuthState int
+
+const (
+	// AuthUnknown indicates the auth probe was not run for this state.
+	AuthUnknown AuthState = iota
+	// AuthAuthed indicates the probe confirmed a usable token.
+	AuthAuthed
+	// AuthUnauthed indicates the probe confirmed login is needed.
+	AuthUnauthed
+)
+
+// State is the snapshot resolvers operate on. AssembleState builds one per
+// call; there is no shared singleton or cross-command cache. Fields
+// marked optional below are populated only by the resolver paths that
+// need them — see field docs.
+type State struct {
+	// HasProjectEndpoint reports whether AZURE_AI_PROJECT_ENDPOINT is set
+	// (and non-empty) in the active azd environment.
+	HasProjectEndpoint bool
+
+	// 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
+	// surface an actionable hint.
+	MissingInfraVars []string
+
+	// MissingManualVars names ${...} references that map to user-supplied
+	// variables which are not set in the azd environment.
+	MissingManualVars []string
+
+	// Services is the per-service snapshot derived from azure.yaml plus
+	// the azd environment (for IsDeployed).
+	Services []ServiceState
+
+	// AgentStatus is the remote agent version status as reported by the
+	// Foundry API (e.g., "Active", "Creating", "Failed"). Empty when the
+	// caller did not probe the remote API.
+	AgentStatus string
+
+	// HasOpenAPI reports whether OpenAPIPayload has been populated. The
+	// payload is populated only when AssembleState is called from a path
+	// that contacts the agent (e.g., `run`, `doctor`).
+	HasOpenAPI bool
+
+	// OpenAPIPayload is a sample request payload extracted from the
+	// agent's OpenAPI spec, suitable for an `azd ai agent invoke '...'`
+	// example. Empty when HasOpenAPI is false.
+	OpenAPIPayload string
+
+	// IsAuthenticated is populated only by the full-sweep `doctor` path.
+	// Every other resolver receives AuthUnknown and treats
+	// auth-conditional suggestions as "skip" rather than "tell user to
+	// log in".
+	IsAuthenticated AuthState
+}
+
+// ServiceState mirrors one entry from the project's services map, plus a
+// deployment marker derived from azd environment variables. IsDeployed is
+// true when AGENT_<KEY>_VERSION is non-empty in the active environment,
+// where <KEY> is the service name upper-cased with hyphens replaced by
+// underscores — the convention used by the deploy-time env-var writer in
+// project/service_target_agent.go.
+type ServiceState struct {
+	Name         string
+	Host         string
+	Protocol     string
+	RelativePath string
+	IsDeployed   bool
+}