feat(azure.ai.agents): wire deploy-hook Next: block on host artifact

Wires the nextstep package into deployHostedAgent so successful deploys
surface context-aware guidance via the artifact's Metadata["note"].

Implementation:
- service_target_agent.go imports azureaiagent/internal/cmd/nextstep.
- After deployArtifacts() returns, deployHostedAgent calls
  nextstep.AssembleState(ctx, p.azdClient), resolves projectRoot via
  azdClient.Project().Get, then calls augmentDeployNote(...).
- New augmentDeployNote(state, artifacts, projectRoot, configDir) walks
  to the last note-bearing artifact and either REPLACES the aka.ms line
  (when a local README exists) or APPENDS the Next: block below it
  (when no README) — implements collision strategy C2.
- New helpers: lastNoteArtifact and suggestionsIncludeReadme.
- Best-effort: every failure path (nil state, missing project, cache
  miss, README absent) silently skips the augmentation — deploy success
  is never blocked by guidance plumbing.
- Cached OpenAPI bytes resolved via nextstep.ReadCachedOpenAPISpec with
  suffix="local" so the resolver can prefer the spec-derived payload
  over the protocol-generic literal when available.

Tests (service_target_agent_test.go): 7 new TestAugmentDeployNote_* cases
covering: README absence (append below aka.ms), README presence
(replace aka.ms), cached spec yielding payload override, attachment
point selection (last endpoint), and three no-op contracts (nil state,
no note-bearing artifact, no services). The cached-spec test uses the
singular OpenAPI 3.0 'example' key — ExtractInvokeExample does NOT walk
the plural 'examples' map (see openapi.go for the resolution order).

Pre-existing TestDeployArtifacts_* tests still pass; deployArtifacts is
byte-for-byte unchanged. Live-smoke verified against the deployed
hello-world-python-invocations sample: aka.ms line correctly replaced,
3 aligned suggestion rows surface.

Refs PR Azure#8057 critique items C2 (collision strategy) and design
strategy delta D21 (dropped currentIndentation arg from
FormatNextForNote — caller indent is unknown to the extension).

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

Author: Antriksh Jain

cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent.go

@@ -24,6 +24,7 @@ import (
 	"strings"
 	"time"
 
+	"azureaiagent/internal/cmd/nextstep"
 	"azureaiagent/internal/exterrors"
 	"azureaiagent/internal/pkg/agents"
 	"azureaiagent/internal/pkg/agents/agent_api"
@@ -970,6 +971,22 @@ func (p *AgentServiceTargetProvider) finalizeDeploy(
 		protocols,
 	)
 
+	// Best-effort: enrich the last endpoint artifact's note with a
+	// context-aware "Next:" block. Failures are non-fatal — the static
+	// aka.ms link emitted by deployArtifacts is preserved when the
+	// enrichment is skipped or short-circuits.
+	if state, _ := nextstep.AssembleState(ctx, p.azdClient); state != nil {
+		projectRoot := ""
+		if proj, err := p.azdClient.Project().Get(ctx, nil); err == nil && proj.Project != nil {
+			projectRoot = proj.Project.Path
+		}
+		configDir := ""
+		if projectRoot != "" && p.env != nil && p.env.Name != "" {
+			configDir = filepath.Join(projectRoot, ".azure", p.env.Name)
+		}
+		augmentDeployNote(state, artifacts, projectRoot, configDir)
+	}
+
 	return &azdext.ServiceDeployResult{
 		Artifacts: artifacts,
 	}, nil
@@ -1550,6 +1567,110 @@ func (p *AgentServiceTargetProvider) deployArtifacts(
 	return artifacts
 }
 
+// augmentDeployNote enriches the last endpoint artifact's note with a
+// context-aware "Next:" block resolved from the provided state.
+//
+// Collision rule with the static aka.ms link emitted by deployArtifacts:
+//
+//   - When the resolved block contains a "see <relPath>/README.md"
+//     suggestion (i.e. a local README exists at the service path), the
+//     aka.ms line is replaced entirely — the block already points the
+//     user at the more-detailed local doc, so the canned link is
+//     redundant.
+//   - Otherwise the aka.ms line is preserved and the "Next:" block is
+//     appended below, separated by a blank line — aka.ms remains the
+//     fallback doc pointer when no local README is present.
+//
+// The function is a no-op when state is nil, no artifact carries a note,
+// or the resolver returns no suggestions; this keeps the deploy path
+// resilient to partial state (e.g. project metadata unavailable) without
+// silencing the original static guidance.
+func augmentDeployNote(state *nextstep.State, artifacts []*azdext.Artifact, projectRoot, configDir string) {
+	if state == nil {
+		return
+	}
+
+	target := lastNoteArtifact(artifacts)
+	if target == nil {
+		return
+	}
+
+	cachedPayload := func(serviceName string) string {
+		if configDir == "" || serviceName == "" {
+			return ""
+		}
+		spec, err := nextstep.ReadCachedOpenAPISpec(configDir, serviceName, "local")
+		if err != nil {
+			return ""
+		}
+		return nextstep.ExtractInvokeExample(spec)
+	}
+
+	readmeExists := func(relativePath string) bool {
+		if projectRoot == "" || relativePath == "" {
+			return false
+		}
+		for _, name := range []string{"README.md", "readme.md", "README.MD"} {
+			if _, err := os.Stat(filepath.Join(projectRoot, relativePath, name)); err == nil {
+				return true
+			}
+		}
+		return false
+	}
+
+	suggestions := nextstep.ResolveAfterDeploy(state, cachedPayload, readmeExists)
+	if len(suggestions) == 0 {
+		return
+	}
+
+	block := nextstep.FormatNextForNote(suggestions)
+	if block == "" {
+		return
+	}
+
+	if suggestionsIncludeReadme(suggestions) {
+		target.Metadata["note"] = block
+		return
+	}
+	existing := target.Metadata["note"]
+	if existing == "" {
+		target.Metadata["note"] = block
+		return
+	}
+	target.Metadata["note"] = existing + "\n\n" + block
+}
+
+// lastNoteArtifact returns the last artifact in the slice whose
+// Metadata["note"] is non-empty, or nil when none of the artifacts
+// carry a note. deployArtifacts attaches its informational note to the
+// final endpoint artifact only; scanning from the end keeps this in
+// sync should the convention shift to multi-note artifacts in future.
+func lastNoteArtifact(artifacts []*azdext.Artifact) *azdext.Artifact {
+	for i := len(artifacts) - 1; i >= 0; i-- {
+		a := artifacts[i]
+		if a == nil || a.Metadata == nil {
+			continue
+		}
+		if a.Metadata["note"] != "" {
+			return a
+		}
+	}
+	return nil
+}
+
+// suggestionsIncludeReadme reports whether any suggestion is a local-README
+// pointer (ResolveAfterDeploy emits these as "see <relPath>/README.md").
+// Used by augmentDeployNote to decide whether to replace or append to the
+// existing static aka.ms note.
+func suggestionsIncludeReadme(suggestions []nextstep.Suggestion) bool {
+	for _, s := range suggestions {
+		if strings.HasPrefix(s.Command, "see ") && strings.HasSuffix(s.Command, "README.md") {
+			return true
+		}
+	}
+	return false
+}
+
 // protocolEndpointInfo holds a displayable protocol label and its invocation URL.
 type protocolEndpointInfo struct {
 	Protocol string

cli/azd/extensions/azure.ai.agents/internal/project/service_target_agent_test.go

@@ -10,9 +10,11 @@ import (
 	"net"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync/atomic"
 	"testing"
 
+	"azureaiagent/internal/cmd/nextstep"
 	"azureaiagent/internal/exterrors"
 	"azureaiagent/internal/pkg/agents/agent_api"
 	"azureaiagent/internal/pkg/agents/agent_yaml"
@@ -1068,3 +1070,210 @@ func actionableStatusError(t *testing.T, message, suggestion string) error {
 	require.NoError(t, err)
 	return stWithDetails.Err()
 }
+
+func TestAugmentDeployNote_NoReadme_AppendsBelowAkaMsLink(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	// No README written; readmeExists closure should return false.
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{
+				Name:         "echo",
+				RelativePath: "src/echo",
+				Protocol:     "invocations",
+				IsDeployed:   true,
+			},
+		},
+	}
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{artifact}, tmp, "" /* no configDir → cache lookup is a no-op */)
+
+	got := artifact.Metadata["note"]
+	require.Contains(t, got, "static aka.ms link", "aka.ms link should be preserved when no README is present")
+	require.Contains(t, got, "Next:", "Next: block should be appended")
+	require.Contains(t, got, "azd ai agent invoke ", "should suggest invoking the deployed agent")
+	require.Equal(t, 1, strings.Count(got, "Next:"), "Next: header should appear exactly once")
+}
+
+func TestAugmentDeployNote_WithReadme_ReplacesAkaMsLink(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	servicePath := filepath.Join(tmp, "src", "echo")
+	require.NoError(t, os.MkdirAll(servicePath, 0o750))
+	require.NoError(t, os.WriteFile(filepath.Join(servicePath, "README.md"), []byte("sample"), 0o600))
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{
+				Name:         "echo",
+				RelativePath: "src/echo",
+				Protocol:     "invocations",
+				IsDeployed:   true,
+			},
+		},
+	}
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{artifact}, tmp, "")
+
+	got := artifact.Metadata["note"]
+	require.NotContains(t, got, "static aka.ms link",
+		"aka.ms line must be replaced when a local README provides richer guidance")
+	require.Contains(t, got, "Next:", "Next: block should be present")
+	require.Contains(t, got, "see src/echo/README.md", "README pointer should be present")
+}
+
+func TestAugmentDeployNote_CachedSpecYieldsPayloadOverride(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	configDir := filepath.Join(tmp, ".azure", "dev")
+	require.NoError(t, os.MkdirAll(configDir, 0o750))
+	// ReadCachedOpenAPISpec / sanitizeAgentName: the filename uses the agent
+	// name verbatim when it contains only safe characters.
+	spec := `{
+  "paths": {
+    "/invocations": {
+      "post": {
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "example": {"prompt": "from cache"}
+            }
+          }
+        }
+      }
+    }
+  }
+}`
+	require.NoError(t, os.WriteFile(filepath.Join(configDir, "openapi-echo-local.json"), []byte(spec), 0o600))
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{
+				Name:         "echo",
+				RelativePath: "src/echo",
+				Protocol:     "invocations",
+				IsDeployed:   true,
+			},
+		},
+	}
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{artifact}, tmp, configDir)
+
+	got := artifact.Metadata["note"]
+	require.Contains(t, got, `"prompt":"from cache"`,
+		"cached OpenAPI example should drive the suggested invoke payload")
+}
+
+func TestAugmentDeployNote_NoteAttachedToLastEndpoint(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{
+				Name:         "echo",
+				RelativePath: "src/echo",
+				Protocol:     "invocations",
+				IsDeployed:   true,
+			},
+		},
+	}
+
+	playground := &azdext.Artifact{
+		Kind:     azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{"label": "Agent playground (portal)"},
+	}
+	first := &azdext.Artifact{
+		Kind:     azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{"label": "Agent endpoint (responses)"},
+	}
+	last := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+
+	augmentDeployNote(state, []*azdext.Artifact{playground, first, last}, tmp, "")
+
+	require.NotContains(t, playground.Metadata["note"], "Next:", "playground artifact must remain untouched")
+	require.NotContains(t, first.Metadata["note"], "Next:", "non-note endpoint must remain untouched")
+	require.Contains(t, last.Metadata["note"], "Next:", "augmentation must target the last note-bearing artifact")
+}
+
+func TestAugmentDeployNote_NilStateIsNoOp(t *testing.T) {
+	t.Parallel()
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+	augmentDeployNote(nil, []*azdext.Artifact{artifact}, "/tmp", "")
+	require.Equal(t, "static aka.ms link", artifact.Metadata["note"], "nil state must leave the static note intact")
+}
+
+func TestAugmentDeployNote_NoNoteBearingArtifactIsNoOp(t *testing.T) {
+	t.Parallel()
+
+	state := &nextstep.State{
+		Services: []nextstep.ServiceState{
+			{Name: "echo", RelativePath: "src/echo", Protocol: "invocations", IsDeployed: true},
+		},
+	}
+	playground := &azdext.Artifact{
+		Kind:     azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{"label": "Agent playground (portal)"},
+	}
+	augmentDeployNote(state, []*azdext.Artifact{playground}, "/tmp", "")
+	require.Empty(t, playground.Metadata["note"], "no note-bearing artifact → nothing to augment")
+}
+
+// TestAugmentDeployNote_NoServicesIsNoOp covers a partial-state branch:
+// ResolveAfterDeploy short-circuits on len(state.Services) == 0, so the
+// existing static note must survive unchanged.
+func TestAugmentDeployNote_NoServicesIsNoOp(t *testing.T) {
+	t.Parallel()
+
+	artifact := &azdext.Artifact{
+		Kind: azdext.ArtifactKind_ARTIFACT_KIND_ENDPOINT,
+		Metadata: map[string]string{
+			"label": "Agent endpoint (invocations)",
+			"note":  "static aka.ms link",
+		},
+	}
+	augmentDeployNote(&nextstep.State{}, []*azdext.Artifact{artifact}, "/tmp", "")
+	require.Equal(t, "static aka.ms link", artifact.Metadata["note"])
+}