feat(azure.ai.agents): align show non-Active branches with issue Azure#7975 vocabulary (P5.1 C5)

Fixes B8: `azd ai agent show` returned `monitor --tail 100` on
failed status and a `show` re-check on empty status. Per issue
Azure#7975 lines 208-214 the vocabulary is:

  IF status == "active" OR status == "idle":
      -> "azd ai agent invoke <agent> 'Hello!'"
  IF status == "failed" OR status == "":
      -> "azd ai agent monitor --follow"
  ELSE:
      -> "azd ai agent show <agent>"  (transitional re-check)

Three changes:

1. New `AgentVersionIdle = "idle"` constant in error_codes.go.
   The verified platform enum (see error_codes.go:64-71 doc)
   only emits `active` today, but the issue spec treats `idle`
   as a "ready" synonym. We add it defensively so a future API
   surface change wouldn't make this branch return the wrong
   suggestion. The Active branch's switch case now reads
   `case AgentVersionActive, AgentVersionIdle:`.

2. `AgentVersionFailed` switch arm now emits
   `azd ai agent monitor --follow` (was `--tail 100`). By the
   time `show` surfaces the failure, the interactive user wants
   to watch the live tail of the next reconcile attempt, not
   capture a fixed 100-line window. The pre-C5 `--tail 100`
   behavior is preserved in the *invoke*-failure paths
   (resolver.go:291,300; error_codes.go:143) — those are
   post-mortem inspections after a 5xx response and have
   different intent.

3. Empty status (`AgentStatus == ""`) is now combined with the
   Failed arm via `case AgentVersionFailed, "":`. The previous
   fall-through to the unknown/transitional `show` re-check
   masked the case where the platform genuinely had no status
   to report — the live log feed is the most useful next view
   when "we don't know yet".

Genuinely unknown statuses (anything not in the AgentVersionStatus
enum and not "") still fall through to the unknown branch, which
emits an `azd ai agent show <svc>` re-check.

Tests:
- resolver_test.go TestResolveAfterShow table: bumped `Failed`
  case from `monitor --tail 100` → `monitor --follow`, added
  `Idle` row routing to invoke, flipped `empty status` row from
  re-check → `monitor --follow`.
- show_test.go TestResolveNextStepFromSource_NonActiveBranches:
  bumped the `failed` row from `--tail 100` → `--follow`.

Doc comment on `ResolveAfterShow` now includes the full status
mapping table (single source of truth in the code).

Scope: ~40 LoC + doc/test updates. Independent of C1-C4.

Source of truth: issue Azure#7975 lines 207-214 + P5.1 commit plan C5.

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

Author: Antriksh Jain

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

@@ -68,6 +68,10 @@ const (
 // Empirical verification: `azd ai agent show` returns "active" for a
 // ready agent. The design-spec table uses title-case for readability
 // only; the canonical surface is lowercase.
+//
+// One member of this type — AgentVersionIdle — is a defensive
+// synonym not currently observed in the platform's verified enum;
+// see its doc comment for rationale.
 type AgentVersionStatus string
 
 const (
@@ -76,6 +80,12 @@ const (
 	// AgentVersionActive indicates the deploy succeeded and the agent is
 	// ready to receive invocations.
 	AgentVersionActive AgentVersionStatus = "active"
+	// AgentVersionIdle is a defensive synonym for "active" — the issue
+	// #7975 spec lists `idle` alongside `active` as a "ready" state
+	// (lines 208-209), although the platform's verified enum only emits
+	// `active` today. Treat any `idle` value the API may surface in the
+	// future the same as `active` (route to the invoke suggestion).
+	AgentVersionIdle AgentVersionStatus = "idle"
 	// AgentVersionFailed indicates the deploy failed; the error payload
 	// carries the structured reason.
 	AgentVersionFailed AgentVersionStatus = "failed"

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

@@ -317,6 +317,16 @@ func resolveInvokeFailure(_ *State, mode InvokeMode, _ string, failure *InvokeFa
 // successful `azd ai agent show`. Branches on State.AgentStatus per the
 // platform's `AgentVersionStatus` vocabulary.
 //
+// Status mapping (issue #7975 lines 208-214):
+//   - active / idle  → `azd ai agent invoke <svc> "Hello!"` (ready to test)
+//   - creating       → `azd ai agent monitor --type system --follow`
+//   - failed / ""    → `azd ai agent monitor --follow` (live log feed,
+//     used to be `--tail 100` pre-C5; spec calls for `--follow` so
+//     the user can watch the next reconcile attempt stream live)
+//   - deleting / deleted → `azd deploy` (redeploy)
+//   - anything else (transitional / genuinely unknown) → `azd ai agent
+//     show <svc>` re-check
+//
 // serviceName is the azure.yaml service name. It is used end-to-end:
 // (1) to look up State.Services[].Protocol for the protocol-aware
 // payload, (2) as the positional in the suggested
@@ -339,7 +349,11 @@ func ResolveAfterShow(state *State, serviceName string) []Suggestion {
 	}
 
 	switch AgentVersionStatus(state.AgentStatus) {
-	case AgentVersionActive:
+	case AgentVersionActive, AgentVersionIdle:
+		// Issue #7975 line 208: `idle` is a defensive synonym for
+		// `active`. The platform's verified enum only emits `active`
+		// today, but if the API ever surfaces `idle` we treat it the
+		// same — both mean "ready to invoke".
 		protocol := ProtocolResponses
 		if svc := findService(state, serviceName); svc != nil && svc.Protocol != "" {
 			protocol = svc.Protocol
@@ -356,9 +370,28 @@ func ResolveAfterShow(state *State, serviceName string) []Suggestion {
 			Priority:    10,
 		}}
 	case AgentVersionFailed:
+		// Issue #7975 line 211: failed status maps to `monitor
+		// --follow`. The historical `--tail 100` was useful for
+		// one-shot CI inspection but the interactive default is the
+		// live tail — by the time `show` surfaces the failure, the
+		// user wants to watch the next reconcile attempt stream
+		// rather than capture a fixed-size window.
 		return []Suggestion{{
-			Command:     "azd ai agent monitor --tail 100",
-			Description: "deploy failed — view the structured error and TSG link above",
+			Command:     "azd ai agent monitor --follow",
+			Description: "stream agent logs to investigate the failure",
+			Priority:    10,
+		}}
+	case "":
+		// Issue #7975 line 210: empty status also routes to `monitor
+		// --follow`, but the framing differs from the Failed arm —
+		// here the platform simply hasn't reported a Status yet (the
+		// `show` table even suppresses the Status row in this case;
+		// see show.go printShowResultTable). The most useful next
+		// view is the live log feed, but we don't presume a failure
+		// occurred.
+		return []Suggestion{{
+			Command:     "azd ai agent monitor --follow",
+			Description: "stream agent logs — status has not been reported yet",
 			Priority:    10,
 		}}
 	case AgentVersionDeleting, AgentVersionDeleted:

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

@@ -563,11 +563,12 @@ func TestResolveAfterShow(t *testing.T) {
 		wantCmdHas string
 	}{
 		{"Active without service in state → responses payload", AgentVersionActive, "echo", `azd ai agent invoke echo "Hello!"`},
+		{"Idle (defensive synonym for Active) → invoke", AgentVersionIdle, "echo", `azd ai agent invoke echo "Hello!"`},
 		{"Creating → monitor system", AgentVersionCreating, "echo", "azd ai agent monitor --type system --follow"},
-		{"Failed → monitor tail", AgentVersionFailed, "echo", "azd ai agent monitor --tail 100"},
+		{"Failed → monitor --follow", AgentVersionFailed, "echo", "azd ai agent monitor --follow"},
 		{"Deleting → redeploy", AgentVersionDeleting, "echo", "azd deploy"},
 		{"Deleted → redeploy", AgentVersionDeleted, "echo", "azd deploy"},
-		{"empty status → re-check show", "", "echo", "azd ai agent show echo"},
+		{"empty status → monitor --follow", "", "echo", "azd ai agent monitor --follow"},
 		{"unknown status → re-check show", "Transitioning", "echo", "azd ai agent show echo"},
 		{"unknown status without agent name → bare show", "Transitioning", "", "azd ai agent show"},
 	}

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

@@ -450,7 +450,8 @@ func TestResolveNextStepFromSource_NonActiveBranches(t *testing.T) {
 		want   string
 	}{
 		{"creating", "azd ai agent monitor --type system --follow"},
-		{"failed", "azd ai agent monitor --tail 100"},
+		{"failed", "azd ai agent monitor --follow"},
+		{"", "azd ai agent monitor --follow"},
 		{"deleting", "azd deploy"},
 		{"deleted", "azd deploy"},
 	}