From 380239594f77c1bd8b4b617624f7831597b3d0fa Mon Sep 17 00:00:00 2001 From: Guillaume Sachet Date: Wed, 8 Jul 2026 16:33:10 +0200 Subject: [PATCH] feat(proto): add search summaries for modules/setups and mission cost in user profile Added new message types `ModuleSummary` and `SetupSummary` to provide trimmed, search-friendly representations of modules and setups. Updated `SearchSetupsRequest` and `SearchModulesRequest` to replace deprecated discovery requests, with filters for organization, visibility, statuses, owner_id, and tags, plus a new `SortBy` enum for result sorting. Updated `ModuleDescriptor` and `SetupDescriptor` to include `tags` for categorization. Also clarified in GetUserProfileRequest that the user is resolved from the mission scope, and added a `mission_cost` field to GetUserProfileResponse representing the total cost accumulated by the mission. (cherry picked from commit f9c6b9acb99a32ab63329f1768512435a6920de5) --- .task/checksum/lint | 1 + .../registry/v1/registry_enums.proto | 14 +- .../registry/v1/registry_models.proto | 92 +++++++++-- .../registry/v1/registry_requests.proto | 148 +++++++++++------- .../registry/v1/registry_service.proto | 10 +- .../user_profile/v1/user_profile.proto | 8 +- 6 files changed, 200 insertions(+), 73 deletions(-) create mode 100644 .task/checksum/lint diff --git a/.task/checksum/lint b/.task/checksum/lint new file mode 100644 index 0000000..ef059a8 --- /dev/null +++ b/.task/checksum/lint @@ -0,0 +1 @@ +983ce0c7462bd60269f34ccf1e520dad diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto b/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto index b77fa14..05e4f70 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto @@ -68,6 +68,18 @@ enum Visibility { VISIBILITY_INTERNAL = 3; } +// Sort key for search results +enum SortBy { + // Backend default: relevance when a query is set, otherwise updated_at descending + SORT_BY_UNSPECIFIED = 0; + // Name + SORT_BY_NAME = 1; + // Created at + SORT_BY_CREATED_AT = 2; + // Updated at + SORT_BY_UPDATED_AT = 3; +} + // ModuleType enum ModuleType { // Unspecified @@ -75,5 +87,5 @@ enum ModuleType { // Archetype MODULE_TYPE_ARCHETYPE = 1; // Tool - MODULE_TYPE_TOOL = 2; + MODULE_TYPE_TOOL_MODULE = 2; } diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_models.proto b/proto/agentic_mesh_protocol/registry/v1/registry_models.proto index 691f084..4af2a09 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_models.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_models.proto @@ -98,16 +98,18 @@ message ModuleDescriptor { // Cost schema google.protobuf.Struct cost_schema = 15 [(buf.validate.field).required = true]; - // Documentation - string documentation = 16 [ - (buf.validate.field).required = true, - (buf.validate.field).string.min_len = 1 - ]; + // Documentation (may be empty) + string documentation = 16; // Created at google.protobuf.Timestamp created_at = 17 [(buf.validate.field).required = true]; // Updated at google.protobuf.Timestamp updated_at = 18 [(buf.validate.field).required = true]; + + // Tags for categorization and search filtering (lowercase recommended) + repeated string tags = 19 [ + (buf.validate.field).repeated.items.string.min_len = 1 + ]; } // Represents your "setups" + current "setup_versions" @@ -123,11 +125,8 @@ message SetupDescriptor { (buf.validate.field).required = true, (buf.validate.field).string.min_len = 1 ]; - // Documentation - string documentation = 3 [ - (buf.validate.field).required = true, - (buf.validate.field).string.min_len = 1 - ]; + // Documentation (may be empty) + string documentation = 3; // Status SetupStatus status = 4 [ (buf.validate.field).required = true, @@ -180,4 +179,77 @@ message SetupDescriptor { // Resolved module info (so agents don't need another round-trip) ModuleDescriptor module = 13 [(buf.validate.field).required = true]; + + // Tags for categorization and search filtering (lowercase recommended) + repeated string tags = 14 [ + (buf.validate.field).repeated.items.string.min_len = 1 + ]; +} + +// Trimmed, search-oriented view of a module. Intentionally excludes the +// network address/port (mesh-internal) and the schema Structs — resolve +// via GetModule when wiring communication. +message ModuleSummary { + // Module ID + string id = 1 [ + (buf.validate.field).required = true, + (buf.validate.field).string.prefix = "modules:", + (buf.validate.field).string.min_len = 1 + ]; + // Name + string name = 2 [ + (buf.validate.field).required = true, + (buf.validate.field).string.min_len = 1 + ]; + // Module type (tool vs archetype/kin) + ModuleType module_type = 3; + // Version + string version = 4; + // Status + ModuleStatus status = 5; + // Visibility + Visibility visibility = 6; + // Organization ID + string organization_id = 7; + // Documentation + string documentation = 8; + // Tags + repeated string tags = 9; +} + +// Trimmed, search-oriented view of a setup. Intentionally excludes the +// setup configuration (may contain sensitive values), owner/card ids and +// the full module descriptor — resolve via GetSetup when invoking. +message SetupSummary { + // Setup ID + string id = 1 [ + (buf.validate.field).required = true, + (buf.validate.field).string.prefix = "setups:", + (buf.validate.field).string.min_len = 1 + ]; + // Name + string name = 2 [ + (buf.validate.field).required = true, + (buf.validate.field).string.min_len = 1 + ]; + // Documentation + string documentation = 3; + // Status + SetupStatus status = 4; + // Visibility + Visibility visibility = 5; + // Organization ID + string organization_id = 6; + // Backing module + string module_id = 7; + // Backing module name (denormalized so search needs no second round-trip) + string module_name = 8; + // Backing module type (tool vs archetype/kin) + ModuleType module_type = 9; + // Current version id + string setup_version_id = 10; + // Current version label + string setup_version = 11; + // Tags + repeated string tags = 12; } diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto b/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto index 0f0e57e..5ea3cb2 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto @@ -18,6 +18,7 @@ package agentic_mesh_protocol.registry.v1; import "agentic_mesh_protocol/registry/v1/registry_enums.proto"; import "agentic_mesh_protocol/registry/v1/registry_models.proto"; + import "buf/validate/validate.proto"; // ------------------------- @@ -49,12 +50,16 @@ message RegisterModuleRequest { (buf.validate.field).required = true, (buf.validate.field).string.min_len = 1 ]; // runtime version of the deployed module + // Module type (tool vs archetype/kin) declared by the module at registration + ModuleType module_type = 5; } // RegisterModuleResponse message RegisterModuleResponse { // Module descriptor - ModuleDescriptor module = 1 [(buf.validate.field).required = true]; + ModuleDescriptor module = 1 [ + (buf.validate.field).required = true + ]; } // HeartbeatRequest @@ -80,78 +85,107 @@ message HeartbeatResponse { // DISCOVERY // ------------------------- -// Discover setups that are available (agents / tools). -message DiscoverSetupsRequest { - // Basic filtering - // Organization ID - string organization_id = 1 [ - (buf.validate.field).string.prefix = "organizations:", - (buf.validate.field).string.min_len = 1 +// Search the setup catalog (configured, invocable agent/tool instances). +message SearchSetupsRequest { + // Free-text search. The backend MUST match case-insensitively against + // BOTH the setup name and its documentation. Empty = match all. + string query = 1; + // Restrict to these setup ids (empty = no filter) + repeated string setup_ids = 2 [ + (buf.validate.field).repeated.items.string.prefix = "setups:" ]; - // Visibility - repeated Visibility visibility = 2 [(buf.validate.field).repeated.items.enum.not_in = 0]; - // Status - repeated SetupStatus status = 3 [(buf.validate.field).repeated.items.enum.not_in = 0]; // typically READY / CONFIGURATION_SUCCEEDED - - // e.g. agent, tool - repeated ModuleType module_types = 4 [(buf.validate.field).repeated.items.enum.not_in = 0]; - - // Simple text search - string query = 5 [(buf.validate.field).string.min_len = 1]; // matches on name / documentation depending on implementation - - // Filter on specific modules if needed - repeated string module_ids = 6 [ - (buf.validate.field).repeated.items.string.prefix = "modules:", + // Restrict to setups backed by these modules (empty = no filter) + repeated string module_ids = 3 [ + (buf.validate.field).repeated.items.string.prefix = "modules:" + ]; + // Filter by backing module type, e.g. tool, archetype (empty = no filter) + repeated ModuleType module_types = 4 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by setup status (empty = no filter); + // typically READY / CONFIGURATION_SUCCEEDED for invocable setups + repeated SetupStatus statuses = 5 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by visibility (empty = no filter) + repeated Visibility visibilities = 6 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by tags (empty = no filter). Matched case-insensitively; a setup + // matches if it carries AT LEAST ONE of the given tags (OR semantics). + repeated string tags = 9 [ (buf.validate.field).repeated.items.string.min_len = 1 ]; - - // Pagination - // Limit - int32 limit = 7 [ - (buf.validate.field).int32.gte = 1, + // Sort key (UNSPECIFIED = backend default) + SortBy sort_by = 10; + // Sort direction: false = ascending, true = descending + bool descending = 11; + // Pagination. limit 0 = server default (20), capped at 100. + int32 limit = 12 [ + (buf.validate.field).int32.gte = 0, (buf.validate.field).int32.lte = 100 ]; // Offset - int32 offset = 8 [(buf.validate.field).int32.gte = 0]; + int32 offset = 13 [ + (buf.validate.field).int32.gte = 0 + ]; } -// DiscoverSetupsResponse -message DiscoverSetupsResponse { - // Setups - repeated SetupDescriptor setups = 1; +// SearchSetupsResponse +message SearchSetupsResponse { + // Matching setups (paginated, trimmed summaries) + repeated SetupSummary setups = 1; + // Total matches ignoring limit/offset, so clients can paginate + int32 total = 2; } -// Discover raw modules (rarely used by agents directly). -message DiscoverModulesRequest { - // Organization ID - string organization_id = 1 [ - (buf.validate.field).string.prefix = "organizations:", - (buf.validate.field).string.min_len = 1 +// Search the module catalog (module blueprints; needs a setup to be invocable). +message SearchModulesRequest { + // Free-text search. The backend MUST match case-insensitively against + // BOTH the module name and its documentation. Empty = match all. + string query = 1; + // Restrict to these module ids (empty = no filter) + repeated string module_ids = 2 [ + (buf.validate.field).repeated.items.string.prefix = "modules:" ]; - // Module types - repeated ModuleType module_types = 2 [(buf.validate.field).repeated.items.enum.not_in = 0]; - // Status - repeated ModuleStatus status = 3 [(buf.validate.field).repeated.items.enum.not_in = 0]; - // Visibility - repeated Visibility visibility = 4 [(buf.validate.field).repeated.items.enum.not_in = 0]; - - // Simple text search - string query = 5 [(buf.validate.field).string.min_len = 1]; // matches on name / documentation - - // Pagination - // Limit - int32 limit = 6 [ - (buf.validate.field).int32.gte = 1, + // Filter by module type, e.g. tool, archetype (empty = no filter) + repeated ModuleType module_types = 3 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by module status (empty = no filter) + repeated ModuleStatus statuses = 4 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by visibility (empty = no filter) + repeated Visibility visibilities = 5 [ + (buf.validate.field).repeated.items.enum.not_in = 0 + ]; + // Filter by tags (empty = no filter). Matched case-insensitively; a module + // matches if it carries AT LEAST ONE of the given tags (OR semantics). + repeated string tags = 8 [ + (buf.validate.field).repeated.items.string.min_len = 1 + ]; + // Sort key (UNSPECIFIED = backend default) + SortBy sort_by = 9; + // Sort direction: false = ascending, true = descending + bool descending = 10; + // Pagination. limit 0 = server default (20), capped at 100. + int32 limit = 11 [ + (buf.validate.field).int32.gte = 0, (buf.validate.field).int32.lte = 100 ]; // Offset - int32 offset = 7 [(buf.validate.field).int32.gte = 0]; + int32 offset = 12 [ + (buf.validate.field).int32.gte = 0 + ]; } -// DiscoverModulesResponse -message DiscoverModulesResponse { - // Modules - repeated ModuleDescriptor modules = 1; +// SearchModulesResponse +message SearchModulesResponse { + // Matching modules (paginated, trimmed summaries) + repeated ModuleSummary modules = 1; + // Total matches ignoring limit/offset, so clients can paginate + int32 total = 2; } // ------------------------- diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_service.proto b/proto/agentic_mesh_protocol/registry/v1/registry_service.proto index 169659a..0c4adb1 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_service.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_service.proto @@ -36,11 +36,13 @@ service RegistryService { // 2. DISCOVERY // ----------------------- - // DEPRECATED: DiscoverSetups — unused in SDK, no callers. - rpc DiscoverSetups(DiscoverSetupsRequest) returns (DiscoverSetupsResponse); + // Search the setup catalog (configured, invocable agent/tool instances). + // Returns trimmed SetupSummary results; resolve full config via GetSetup. + rpc SearchSetups(SearchSetupsRequest) returns (SearchSetupsResponse); - // Discover raw modules (rarely used by agents directly). - rpc DiscoverModules(DiscoverModulesRequest) returns (DiscoverModulesResponse); + // Search the module catalog (module blueprints; needs a setup to be invocable). + // Returns trimmed ModuleSummary results; resolve address/schemas via GetModule. + rpc SearchModules(SearchModulesRequest) returns (SearchModulesResponse); // ----------------------- // 3. RESOLUTION / INFO diff --git a/proto/agentic_mesh_protocol/user_profile/v1/user_profile.proto b/proto/agentic_mesh_protocol/user_profile/v1/user_profile.proto index 7ff392a..7e246b2 100644 --- a/proto/agentic_mesh_protocol/user_profile/v1/user_profile.proto +++ b/proto/agentic_mesh_protocol/user_profile/v1/user_profile.proto @@ -85,7 +85,8 @@ message UserProfile { google.protobuf.Struct metadata = 11; } -// GetUserProfileRequest: Request to get a user profile +// GetUserProfileRequest: Request to get a user profile. +// The user is resolved from the mission scope. message GetUserProfileRequest { // mission_id: Unique identifier for the mission string mission_id = 1 [ @@ -100,6 +101,11 @@ message GetUserProfileResponse { bool success = 1 [(buf.validate.field).required = true]; // user_profile: Retrieved user profile UserProfile user_profile = 2 [(buf.validate.field).required = true]; + // mission_cost: Total cost accumulated so far by the mission in the request + // (sum of its cost entries, same unit as cost.v1 total_cost / CreditLot) + double mission_cost = 3 [ + (buf.validate.field).double.gte = 0 + ]; } // GetSetupSecretRequest