Merge branch 'main' into fix/result-cache-deadlock-623

Author: 7vignesh

CHANGELOG.md

@@ -6,6 +6,94 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 <!-- changelog:entries -->
 
+## [0.1.113] - 2026-07-21
+
+## [0.1.113-rc.1] - 2026-07-21
+
+
+### Added
+
+- Feat: node-declared reasoner descriptions + entry points in discovery and af ls (#805)
+
+* feat(control-plane): per-reasoner descriptions + entrypoint surfacing in discovery and catalog
+
+ReasonerDefinition/SkillDefinition gain a description field (rides in the
+reasoners JSON blob — no migration). Discovery prefers the record-level
+description and falls back to the legacy agent metadata map; the serverless
+ingest path stops dropping the description it already parsed. The reasoner
+catalog (af ls backend) returns description+tags, supports entrypoints=true,
+and sorts entrypoint-tagged rows first among never-run rows. Adds
+types.TagEntrypoint as the shared tag convention.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): af ls shows reasoner descriptions and supports --entrypoints
+
+Rows render a trailing description column ([entrypoint]-labeled when the
+reasoner carries the entrypoint tag, truncated to one line); -e/--entrypoints
+filters to entry points so a caller browsing a node sees its intended surface.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(sdk-go): transmit reasoner descriptions to the control plane
+
+WithDescription was captured locally for CLI help but never sent at
+registration. ReasonerDefinition gains the description field and registerNode
+copies it, so discovery and af ls can surface it.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(sdk-python): description kwarg on @reasoner/@skill with docstring default
+
+@app.reasoner(description=...) / @app.skill(description=...) register a
+caller-facing summary with the control plane; without it, the first paragraph
+of the function docstring (whitespace-collapsed) is used. Routers forward the
+kwarg through include_router unchanged. Payloads without a description are
+byte-identical to before, so older control planes are unaffected.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+---------
+
+Co-authored-by: Claude Fable 5 <noreply@anthropic.com> (075dd32)
+
+## [0.1.112] - 2026-07-21
+
+## [0.1.112-rc.3] - 2026-07-21
+
+
+### Fixed
+
+- Fix: prevent exception details in agent server responses (#800)
+
+Co-authored-by: Abir Abbas <abirabbas1998@gmail.com> (26c8428)
+
+## [0.1.112-rc.2] - 2026-07-21
+
+
+### Chores
+
+- Chore(deps): bump axios (#802)
+
+Bumps the npm_and_yarn group with 1 update in the /sdk/typescript directory: [axios](https://github.com/axios/axios).
+
+
+Updates `axios` from 1.16.0 to 1.18.0
+- [Release notes](https://github.com/axios/axios/releases)
+- [Changelog](https://github.com/axios/axios/blob/v1.x/CHANGELOG.md)
+- [Commits](https://github.com/axios/axios/compare/v1.16.0...v1.18.0)
+
+---
+updated-dependencies:
+- dependency-name: axios
+  dependency-version: 1.18.0
+  dependency-type: direct:production
+  dependency-group: npm_and_yarn
+...
+
+Signed-off-by: dependabot[bot] <support@github.com>
+Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> (4867040)
+
 ## [0.1.112-rc.1] - 2026-07-20
 
 

VERSION

@@ -1 +1 @@
-0.1.112-rc.1
+0.1.113

control-plane/internal/cli/ls_reasoners.go

@@ -17,6 +17,7 @@ type lsOptions struct {
 	all          bool
 	node         string
 	live         bool
+	entrypoints  bool
 	outputFormat string
 	stdout       io.Writer
 	stdoutTTY    bool
@@ -29,10 +30,12 @@ type reasonerListResponse struct {
 }
 
 type reasonerListItem struct {
-	Node      string  `json:"node"`
-	Reasoner  string  `json:"reasoner"`
-	LastRunAt *string `json:"last_run_at,omitempty"`
-	Status    string  `json:"status"`
+	Node        string   `json:"node"`
+	Reasoner    string   `json:"reasoner"`
+	Description string   `json:"description,omitempty"`
+	Tags        []string `json:"tags,omitempty"`
+	LastRunAt   *string  `json:"last_run_at,omitempty"`
+	Status      string   `json:"status"`
 }
 
 func NewReasonerListCommand() *cobra.Command {
@@ -57,6 +60,7 @@ func NewReasonerListCommand() *cobra.Command {
 	cmd.Flags().BoolVar(&opts.all, "all", false, "Show every reasoner")
 	cmd.Flags().StringVar(&opts.node, "node", "", "Filter to a single node")
 	cmd.Flags().BoolVar(&opts.live, "live", false, "Only show reasoners whose node is live")
+	cmd.Flags().BoolVarP(&opts.entrypoints, "entrypoints", "e", false, "Only show reasoners tagged as entry points")
 	cmd.Flags().StringVarP(&opts.outputFormat, "output", "o", "", "Output format: pretty, json, yaml")
 	return cmd
 }
@@ -82,6 +86,9 @@ func runReasonerList(ctx context.Context, query string, opts *lsOptions) error {
 	if opts.live {
 		values.Set("live", "true")
 	}
+	if opts.entrypoints {
+		values.Set("entrypoints", "true")
+	}
 	resp, err := makeRequest(ctx, http.MethodGet, appendQuery("/api/v1/reasoners", values), nil, "application/json")
 	if err != nil {
 		return cliExitError{Code: 3, Err: err}
@@ -107,13 +114,39 @@ func renderReasonerList(out io.Writer, resp reasonerListResponse, recentHeader b
 	}
 	for _, item := range resp.Reasoners {
 		name := item.Node + "." + item.Reasoner
-		fmt.Fprintf(out, "%-28s %-12s %s\n", name, relativeTime(item.LastRunAt), item.Status)
+		fmt.Fprintf(out, "%-28s %-12s %-6s %s\n", name, relativeTime(item.LastRunAt), item.Status, describeReasoner(item))
 	}
 	if resp.Total > resp.Shown {
 		fmt.Fprintf(out, "\n%d more recent  -  %d total  -  use `af ls --all`\n", resp.Total-resp.Shown, resp.Total)
 	}
 }
 
+// describeReasoner renders the trailing description column: entry points are
+// labeled so callers can spot a node's intended surface, and long descriptions
+// are truncated to keep rows on one line.
+func describeReasoner(item reasonerListItem) string {
+	const maxLen = 80
+	desc := strings.Join(strings.Fields(item.Description), " ")
+	if len(desc) > maxLen {
+		desc = desc[:maxLen-1] + "…"
+	}
+	entry := false
+	for _, tag := range item.Tags {
+		if strings.EqualFold(strings.TrimSpace(tag), "entrypoint") {
+			entry = true
+			break
+		}
+	}
+	switch {
+	case entry && desc != "":
+		return "[entrypoint] " + desc
+	case entry:
+		return "[entrypoint]"
+	default:
+		return desc
+	}
+}
+
 func relativeTime(value *string) string {
 	if value == nil || strings.TrimSpace(*value) == "" {
 		return "-"

control-plane/internal/handlers/discovery.go

@@ -517,7 +517,7 @@ func buildDiscoveryResponse(agents []*types.AgentNode, filters DiscoveryFilters)
 				reasonerCap.OutputSchema = decodeSchema(reasoner.OutputSchema)
 			}
 			if filters.IncludeDescriptions {
-				reasonerCap.Description = extractDescription(agent.Metadata, reasoner.ID)
+				reasonerCap.Description = reasonerDescription(agent.Metadata, reasoner)
 			}
 			if filters.IncludeExamples {
 				reasonerCap.Examples = extractExamples(agent.Metadata, reasoner.ID)
@@ -544,7 +544,11 @@ func buildDiscoveryResponse(agents []*types.AgentNode, filters DiscoveryFilters)
 				skillCap.InputSchema = decodeSchema(skill.InputSchema)
 			}
 			if filters.IncludeDescriptions {
-				skillCap.Description = extractDescription(agent.Metadata, skill.ID)
+				if desc := strings.TrimSpace(skill.Description); desc != "" {
+					skillCap.Description = &desc
+				} else {
+					skillCap.Description = extractDescription(agent.Metadata, skill.ID)
+				}
 			}
 
 			capability.Skills = append(capability.Skills, skillCap)
@@ -595,6 +599,16 @@ func decodeSchema(raw json.RawMessage) map[string]interface{} {
 	return schema
 }
 
+// reasonerDescription resolves a reasoner's description: the field the SDK
+// registered on the reasoner record wins; the legacy agent-level
+// metadata.Custom["descriptions"] map remains as a fallback for older SDKs.
+func reasonerDescription(metadata types.AgentMetadata, reasoner types.ReasonerDefinition) *string {
+	if desc := strings.TrimSpace(reasoner.Description); desc != "" {
+		return &desc
+	}
+	return extractDescription(metadata, reasoner.ID)
+}
+
 func extractDescription(metadata types.AgentMetadata, id string) *string {
 	if metadata.Custom == nil {
 		return nil

control-plane/internal/handlers/discovery_test.go

@@ -96,6 +96,45 @@ func TestDiscoveryCapabilities_WithFiltersAndSchemas(t *testing.T) {
 	assert.Empty(t, resp.Capabilities[0].Skills)
 }
 
+// Validation contract: a description registered on the reasoner/skill record
+// itself (new SDKs) must win over the legacy agent-level metadata map, and
+// records without one must still fall back to that map (old SDKs).
+func TestDiscoveryCapabilities_RecordLevelDescriptions(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	InvalidateDiscoveryCache()
+
+	agents := buildDiscoveryAgents()
+	// agent-alpha's reasoner+skill gain record-level descriptions that differ
+	// from the metadata map entries; agent-beta stays metadata-map-only.
+	agents[0].Reasoners[0].Description = "Record-level reasoner description"
+	agents[0].Skills[0].Description = "Record-level skill description"
+
+	lister := &stubAgentLister{agents: agents}
+	router := gin.New()
+	router.GET("/api/v1/discovery/capabilities", DiscoveryCapabilitiesHandler(lister))
+
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/discovery/capabilities", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	require.Equal(t, http.StatusOK, rec.Code)
+	var resp DiscoveryResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	require.Len(t, resp.Capabilities, 2)
+
+	alpha := resp.Capabilities[0]
+	require.Equal(t, "agent-alpha", alpha.AgentID)
+	require.NotNil(t, alpha.Reasoners[0].Description)
+	assert.Equal(t, "Record-level reasoner description", *alpha.Reasoners[0].Description)
+	require.NotNil(t, alpha.Skills[0].Description)
+	assert.Equal(t, "Record-level skill description", *alpha.Skills[0].Description)
+
+	beta := resp.Capabilities[1]
+	require.Equal(t, "agent-beta", beta.AgentID)
+	require.NotNil(t, beta.Reasoners[0].Description)
+	assert.Equal(t, "Performs comprehensive research", *beta.Reasoners[0].Description)
+}
+
 func TestDiscoveryCapabilities_Formats(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	InvalidateDiscoveryCache()

control-plane/internal/handlers/nodes_register.go

@@ -930,6 +930,7 @@ func RegisterServerlessAgentHandler(storageProvider storage.StorageProvider, uiS
 			outputSchemaBytes, _ := json.Marshal(r.OutputSchema)
 			reasoners[i] = types.ReasonerDefinition{
 				ID:           r.ID,
+				Description:  r.Description,
 				InputSchema:  json.RawMessage(inputSchemaBytes),
 				OutputSchema: json.RawMessage(outputSchemaBytes),
 				Tags:         r.Tags,
@@ -946,6 +947,7 @@ func RegisterServerlessAgentHandler(storageProvider storage.StorageProvider, uiS
 			inputSchemaBytes, _ := json.Marshal(s.InputSchema)
 			skills[i] = types.SkillDefinition{
 				ID:          s.ID,
+				Description: s.Description,
 				InputSchema: json.RawMessage(inputSchemaBytes),
 				Tags:        s.Tags,
 			}

control-plane/internal/handlers/reasoner_catalog.go

@@ -22,10 +22,12 @@ type ReasonerCatalogStore interface {
 }
 
 type ReasonerCatalogRow struct {
-	Node      string  `json:"node"`
-	Reasoner  string  `json:"reasoner"`
-	LastRunAt *string `json:"last_run_at,omitempty"`
-	Status    string  `json:"status"`
+	Node        string   `json:"node"`
+	Reasoner    string   `json:"reasoner"`
+	Description string   `json:"description,omitempty"`
+	Tags        []string `json:"tags,omitempty"`
+	LastRunAt   *string  `json:"last_run_at,omitempty"`
+	Status      string   `json:"status"`
 }
 
 type ReasonerCatalogResponse struct {
@@ -70,6 +72,7 @@ func ListReasonersHandler(store ReasonerCatalogStore) gin.HandlerFunc {
 		nodeFilter := strings.TrimSpace(c.Query("node"))
 		liveOnly := parseQueryBool(c.Query("live"))
 		showAll := parseQueryBool(c.Query("all"))
+		entrypointsOnly := parseQueryBool(c.Query("entrypoints"))
 
 		rows := make([]ReasonerCatalogRow, 0)
 		for _, agent := range agents {
@@ -84,6 +87,9 @@ func ListReasonersHandler(store ReasonerCatalogStore) gin.HandlerFunc {
 				continue
 			}
 			for _, reasoner := range agent.Reasoners {
+				if entrypointsOnly && !hasTag(reasoner.Tags, types.TagEntrypoint) {
+					continue
+				}
 				fullName := agent.ID + "." + reasoner.ID
 				if query != "" && !fuzzyReasonerMatch(fullName, query) {
 					continue
@@ -93,11 +99,19 @@ func ListReasonersHandler(store ReasonerCatalogStore) gin.HandlerFunc {
 					formatted := ts.Format(time.RFC3339)
 					lastRun = &formatted
 				}
+				description := strings.TrimSpace(reasoner.Description)
+				if description == "" {
+					if fromMeta := extractDescription(agent.Metadata, reasoner.ID); fromMeta != nil {
+						description = strings.TrimSpace(*fromMeta)
+					}
+				}
 				rows = append(rows, ReasonerCatalogRow{
-					Node:      agent.ID,
-					Reasoner:  reasoner.ID,
-					LastRunAt: lastRun,
-					Status:    status,
+					Node:        agent.ID,
+					Reasoner:    reasoner.ID,
+					Description: description,
+					Tags:        reasoner.Tags,
+					LastRunAt:   lastRun,
+					Status:      status,
 				})
 			}
 		}
@@ -111,6 +125,13 @@ func ListReasonersHandler(store ReasonerCatalogStore) gin.HandlerFunc {
 			if leftOK && !left.Equal(right) {
 				return left.After(right)
 			}
+			// Among never-run (or same-timestamp) rows, surface declared entry
+			// points first so a fresh registry lists callable surfaces on top.
+			leftEntry := hasTag(rows[i].Tags, types.TagEntrypoint)
+			rightEntry := hasTag(rows[j].Tags, types.TagEntrypoint)
+			if leftEntry != rightEntry {
+				return leftEntry
+			}
 			return rows[i].Node+"."+rows[i].Reasoner < rows[j].Node+"."+rows[j].Reasoner
 		})
 
@@ -256,6 +277,15 @@ func reasonerNodeStatus(agent *types.AgentNode) string {
 	}
 }
 
+func hasTag(tags []string, want string) bool {
+	for _, tag := range tags {
+		if strings.EqualFold(strings.TrimSpace(tag), want) {
+			return true
+		}
+	}
+	return false
+}
+
 func fuzzyReasonerMatch(value, query string) bool {
 	value = strings.ToLower(value)
 	query = strings.ToLower(strings.TrimSpace(query))