From 7443413bcd01873237285c44ac289822b2660a51 Mon Sep 17 00:00:00 2001 From: Guillaume Sachet Date: Fri, 28 Aug 2026 09:19:12 +0200 Subject: [PATCH] feat(protocol)!: rework registry, setup, storage and filesystem services Registry: - Replace DiscoverModules/DiscoverSetups with SearchModules/SearchSetups, filtering on organization, visibility, statuses, owner_id and tags with a SortBy enum, returning trimmed ModuleSummary/SetupSummary payloads - Add tags to ModuleDescriptor and SetupDescriptor - Add MODULE_TYPE_SERVICE and rename MODULE_TYPE_TOOL to MODULE_TYPE_TOOL_MODULE Setup: - Slim SetupService to CRUD + ChangeVisibility, dropping the deprecated setup-version and ListSetups RPCs and their messages - CreateSetup takes name + content; the server resolves owner/org and generates id - Add ListSetupVersions (newest first, limit/offset/total_count) exposing current_setup_version_id, and SetCurrentSetupVersion - Add UpdateSetupRequest.set_as_current to promote the created version in one call - Add a local Visibility enum and a visibility field on Setup Storage and filesystem: - Add a local Visibility enum (PUBLIC/PRIVATE/INTERNAL) on records and files, with visibility filters reactivating the ListRecords and GetFiles RPCs - Add a globally unique storage_id to StorageRecord and allow reading by it; paginate ListRecords and scope RemoveCollection to records - Type request context as a ContextStorage/ContextFile enum, the matching entity id being resolved server-side from the task metadata; persisted StorageRecord and File keep their prefixed string context User profile: - Resolve the user from the mission scope and return mission_cost Also documents the git convention forbidding Co-Authored-By trailers. BREAKING CHANGE: the context field changes from string to enum in StoreRecord, ReadRecord, UpdateRecord, RemoveRecord, ListRecords, RemoveCollection, UploadFile, GetFile, UpdateFile, GetFiles and DeleteFiles requests, and the "default" upload context is dropped. The SetupService RPC surface and messages changed, RegistryService drops DiscoverModules and DiscoverSetups, and ModuleType value 2 is renamed to MODULE_TYPE_TOOL_MODULE. --- CLAUDE.md | 5 + .../filesystem/v1/filesystem.proto | 83 +++-- .../filesystem/v1/filesystem_service.proto | 3 +- .../registry/v1/registry_enums.proto | 16 +- .../registry/v1/registry_models.proto | 88 +++++- .../registry/v1/registry_requests.proto | 125 ++++---- .../registry/v1/registry_service.proto | 10 +- .../setup/v1/setup.proto | 299 ++++++++---------- .../setup/v1/setup_service.proto | 31 +- .../storage/v1/data.proto | 99 ++++-- .../storage/v1/storage_service.proto | 2 +- .../user_profile/v1/user_profile.proto | 6 +- 12 files changed, 452 insertions(+), 315 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d48f80f..0270acd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -377,6 +377,11 @@ Automatically pushes schema to Buf Schema Registry: **Note**: All CI workflows use concurrency groups to cancel in-progress runs when new commits are pushed. +## Git Conventions + +### Commit Messages +- **Never add a `Co-Authored-By:` trailer to commits.** This includes AI/assistant co-author trailers (e.g. `Co-Authored-By: Claude ... `) and any other co-author attribution. Commits must carry only their author. + ## Important Notes ### Protocol and Structure diff --git a/proto/agentic_mesh_protocol/filesystem/v1/filesystem.proto b/proto/agentic_mesh_protocol/filesystem/v1/filesystem.proto index 75fa638..0cd4c47 100644 --- a/proto/agentic_mesh_protocol/filesystem/v1/filesystem.proto +++ b/proto/agentic_mesh_protocol/filesystem/v1/filesystem.proto @@ -56,6 +56,33 @@ enum FileStatus { FILE_STATUS_DELETED = 5; } +// Visibility represents the access scope of a file. +enum Visibility { + // VISIBILITY_UNSPECIFIED is the default unspecified value. + VISIBILITY_UNSPECIFIED = 0; + // VISIBILITY_PUBLIC indicates the file is visible to everyone. + VISIBILITY_PUBLIC = 1; + // VISIBILITY_PRIVATE indicates the file is visible only to the owner. + VISIBILITY_PRIVATE = 2; + // VISIBILITY_INTERNAL indicates the file is visible within the organisation. + VISIBILITY_INTERNAL = 3; +} + +// ContextFile: Type of context a file is scoped to. The matching identifier is resolved +// server-side from the task metadata, so it is not carried by the requests. +enum ContextFile { + // CONTEXT_UNSPECIFIED: Default unspecified context + CONTEXT_UNSPECIFIED = 0; + // CONTEXT_MISSIONS: Context related to missions + CONTEXT_MISSIONS = 1; + // CONTEXT_SETUP: Context related to setup + CONTEXT_SETUP = 2; + // CONTEXT_USERS: Context related to users + CONTEXT_USERS = 3; + // CONTEXT_ORGANIZATIONS: Context related to organizations + CONTEXT_ORGANIZATIONS = 4; +} + // File represents a stored file with comprehensive metadata. message File { // file_id: Unique identifier for the file @@ -64,7 +91,7 @@ message File { (buf.validate.field).string.pattern = "^files:.*$" ]; - // context: Context ID linked to the file + // context: Prefixed identifier of the context owning the file (missions: or setups:) string context = 2 [ (buf.validate.field).required = true, (buf.validate.field).string.pattern = "^(missions:|setups:).*$" @@ -123,6 +150,12 @@ message File { // content: The content of the file bytes content = 12; + + // visibility: Access scope of the file + Visibility visibility = 13 [ + (buf.validate.field).required = true, + (buf.validate.field).enum.not_in = 0 + ]; } // FileFilter contains criteria for querying and filtering files. @@ -136,11 +169,8 @@ message FileFilter { // file_types: Filter by file types repeated FileType file_types = 3 [(buf.validate.field).repeated.items.enum.not_in = 0]; - // context: Filter by context (required for scoping) - string context = 4 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions:|setups:|users:|organizations:).*$" - ]; + // context: Type of context to scope the query to (identifier resolved server-side) + ContextFile context = 4 [(buf.validate.field).required = true]; // created_after: Filter files created after this timestamp google.protobuf.Timestamp created_after = 5; @@ -171,6 +201,9 @@ message FileFilter { // content_type: Filter by content type string content_type = 14; + + // visibilities: Filter by visibility (empty = no filter) + repeated Visibility visibilities = 15 [(buf.validate.field).repeated.items.enum.not_in = 0]; } // FileResult wraps the result of a file operation which may succeed or fail. @@ -186,11 +219,8 @@ message FileResult { // UploadFileData contains the data required for uploading a single file. message UploadFileData { - // context: Context ID for the file - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "(^(missions:|setups:).*$|^default$)" - ]; + // context: Type of context the file is scoped to (identifier resolved server-side) + ContextFile context = 1 [(buf.validate.field).required = true]; // name: Name of the file string name = 2 [ @@ -228,6 +258,9 @@ message UploadFileData { // replace_if_exists: Whether to replace existing file with same name bool replace_if_exists = 8; + + // visibility: Access scope of the file (optional; defaults server-side) + Visibility visibility = 9; } // UploadFilesRequest is the request message for uploading multiple files. @@ -253,8 +286,8 @@ message UploadFilesResponse { // GetFileRequest is the request message for retrieving a specific file. message GetFileRequest { - // context: Context ID for the file - string context = 1 [(buf.validate.field).string.pattern = "^(missions:|setups:).*$"]; + // context: Type of context the file is scoped to (identifier resolved server-side) + ContextFile context = 1 [(buf.validate.field).required = true]; // file_id: File ID string file_id = 2 [ @@ -277,11 +310,8 @@ message GetFileResponse { // UpdateFileRequest is the request message for updating a file. message UpdateFileRequest { - // context: Context ID for the file - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions:|setups:).*$" - ]; + // context: Type of context the file is scoped to (identifier resolved server-side) + ContextFile context = 1 [(buf.validate.field).required = true]; // file_id: Current id of the file string file_id = 2 [ @@ -309,6 +339,9 @@ message UpdateFileRequest { // metadata: New metadata (optional, will merge with existing) google.protobuf.Struct metadata = 8; + + // visibility: New access scope of the file (optional; defaults server-side) + Visibility visibility = 9; } // UpdateFileResponse is the response message for file update operations. @@ -319,11 +352,8 @@ message UpdateFileResponse { // GetFilesRequest is the request message for retrieving multiple files by various criteria. message GetFilesRequest { - // context: Context ID for the files - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions:|setups:|users:|organizations:).*$" - ]; + // context: Type of context the files are scoped to (identifier resolved server-side) + ContextFile context = 1 [(buf.validate.field).required = true]; // filters: How to identify the files FileFilter filters = 2 [(buf.validate.field).required = true]; @@ -355,11 +385,8 @@ message GetFilesResponse { // DeleteFilesRequest is the request message for deleting multiple files. message DeleteFilesRequest { - // context: Context ID for the files - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions:|setups:).*$" - ]; + // context: Type of context the files are scoped to (identifier resolved server-side) + ContextFile context = 1 [(buf.validate.field).required = true]; // filters: How to identify the files FileFilter filters = 2 [(buf.validate.field).required = true]; diff --git a/proto/agentic_mesh_protocol/filesystem/v1/filesystem_service.proto b/proto/agentic_mesh_protocol/filesystem/v1/filesystem_service.proto index 1e471c7..9b7c864 100644 --- a/proto/agentic_mesh_protocol/filesystem/v1/filesystem_service.proto +++ b/proto/agentic_mesh_protocol/filesystem/v1/filesystem_service.proto @@ -30,7 +30,8 @@ service FilesystemService { // DEPRECATED: GetFile — unused in SDK, no callers. rpc GetFile(GetFileRequest) returns (GetFileResponse); - // DEPRECATED: GetFiles — unused in SDK, no callers. + // GetFiles retrieves multiple files matching the given filter, + // with pagination and optional visibility filtering. rpc GetFiles(GetFilesRequest) returns (GetFilesResponse); // UpdateFile allows updating various aspects of a file including diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto b/proto/agentic_mesh_protocol/registry/v1/registry_enums.proto index b77fa14..ca3d29e 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,7 @@ enum ModuleType { // Archetype MODULE_TYPE_ARCHETYPE = 1; // Tool - MODULE_TYPE_TOOL = 2; + MODULE_TYPE_TOOL_MODULE = 2; + // Service + MODULE_TYPE_SERVICE = 3; } diff --git a/proto/agentic_mesh_protocol/registry/v1/registry_models.proto b/proto/agentic_mesh_protocol/registry/v1/registry_models.proto index 691f084..f17f156 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_models.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_models.proto @@ -98,16 +98,16 @@ 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 +123,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 +177,75 @@ 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..09dcf22 100644 --- a/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto +++ b/proto/agentic_mesh_protocol/registry/v1/registry_requests.proto @@ -49,6 +49,10 @@ 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; + // Internal documentation for registry index search. + string documentation = 6; } // RegisterModuleResponse @@ -80,78 +84,81 @@ 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 - ]; - // 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 +// 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:"]; + // 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]; - - // 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:", - (buf.validate.field).repeated.items.string.min_len = 1 - ]; - - // Pagination - // Limit - int32 limit = 7 [ - (buf.validate.field).int32.gte = 1, + // 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]; + // 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 - ]; - // 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, +// 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:"]; + // 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/setup/v1/setup.proto b/proto/agentic_mesh_protocol/setup/v1/setup.proto index 228374c..1d21ec2 100644 --- a/proto/agentic_mesh_protocol/setup/v1/setup.proto +++ b/proto/agentic_mesh_protocol/setup/v1/setup.proto @@ -54,6 +54,25 @@ enum SetupStatus { CONFIGURATION_SUCCEEDED = 9; } +// Visibility +// Represents the visibility scope of a setup. +// +// Fields: +// - VISIBILITY_UNSPECIFIED: Visibility not specified +// - VISIBILITY_PUBLIC: Visible to everyone +// - VISIBILITY_PRIVATE: Visible only to the owner +// - VISIBILITY_INTERNAL: Visible within the organisation +enum Visibility { + // VISIBILITY_UNSPECIFIED: Visibility not specified + VISIBILITY_UNSPECIFIED = 0; + // VISIBILITY_PUBLIC: Visible to everyone + VISIBILITY_PUBLIC = 1; + // VISIBILITY_PRIVATE: Visible only to the owner + VISIBILITY_PRIVATE = 2; + // VISIBILITY_INTERNAL: Visible within the organisation + VISIBILITY_INTERNAL = 3; +} + // SetupVersion // Represents a version of a setup's configuration. // @@ -102,43 +121,8 @@ message Setup { optional SetupVersion current_setup_version = 6; // status: The status of the setup. SetupStatus status = 7 [(buf.validate.field).required = true]; -} - -// CreateSetupRequest -// This request is used to create a new setup. -// -// Fields: -// - name: The name of the setup. -// - organisation_id: The unique identifier of the organisation. -// - owner_id: The owner_id of the setup. -// - module_id: The module identifier associated with the setup. -// - current_setup_version: The unique identifier of the active setup version. -message CreateSetupRequest { - // name: The name of the setup. - string name = 1 [(buf.validate.field).required = true]; - // organisation_id: The unique identifier of the organisation. - string organisation_id = 2 [(buf.validate.field).required = true]; - // owner_id: The owner_id of the setup. - string owner_id = 3 [(buf.validate.field).required = true]; - // module_id: The module identifier associated with the setup. - string module_id = 4 [(buf.validate.field).required = true]; - // current_setup_version: The unique identifier of the active setup version. - optional SetupVersion current_setup_version = 5; - // status: The status of the setup. - SetupStatus status = 6 [(buf.validate.field).required = true]; -} - -// CreateSetupResponse -// Returns the newly created setup status flag. -// -// Fields: -// - success: description flag of the operation. -// - setup: The newly created setup entity. -message CreateSetupResponse { - // success: description flag of the operation. - bool success = 1; - // setup: The newly created setup entity. - Setup setup = 2; + // visibility: The visibility scope of the setup. + Visibility visibility = 8 [(buf.validate.field).required = true]; } // GetSetupRequest @@ -167,37 +151,69 @@ message GetSetupResponse { SetupVersion setup_version = 2; } +// CreateSetupRequest +// This request is used to create a new setup. The owner and organisation are +// resolved from the request context, and the identifier is generated server-side. +// +// Fields: +// - name: The name of the setup. +// - content: The configuration content of the initial setup version. +message CreateSetupRequest { + // name: The name of the setup. + string name = 1 [(buf.validate.field).required = true]; + // content: Key-value pairs for the initial configuration content. + google.protobuf.Struct content = 2 [(buf.validate.field).required = true]; +} + +// CreateSetupResponse +// Returns the newly created setup. +// +// Fields: +// - success: Whether the operation succeeded. +// - setup: The newly created setup entity. +// - setup_version: The newly created setup version. +message CreateSetupResponse { + // success: Whether the operation succeeded. + bool success = 1; + // setup: The newly created setup entity. + Setup setup = 2; + // setup_version: The newly created setup version. + SetupVersion setup_version = 3; +} + // UpdateSetupRequest // This request is used to update an existing setup. // // Fields: -// - name: The unique identifier of the setup to update. -// - owner_id: (Optional) The new owner_id. -// - current_setup_version: (Optional) The new active setup version identifier. +// - setup_id: The unique identifier of the setup to update. +// - name: The new name of the setup. +// - content: The new configuration content. +// - set_as_current: Whether the new version becomes the current one. message UpdateSetupRequest { // setup_id: The unique identifier of the setup. string setup_id = 1 [(buf.validate.field).required = true]; - // name: The unique identifier of the setup to update. + // name: The name of the setup. string name = 2 [(buf.validate.field).required = true]; - // owner_id: The owner_id of the setup. - string owner_id = 3; - // current_setup_version: The unique identifier of the active setup version. - SetupVersion current_setup_version = 4; - // status: The status of the setup. - SetupStatus status = 5 [(buf.validate.field).required = true]; + // content: Key-value pairs for configuration content. + google.protobuf.Struct content = 3 [(buf.validate.field).required = true]; + // set_as_current: Whether the new version becomes the current one. + bool set_as_current = 4; } // UpdateSetupResponse -// Returns the updated setup status flag. +// Returns the updated setup. // // Fields: -// - success: description flag of the operation. +// - success: Whether the operation succeeded. // - setup: The updated setup entity. +// - setup_version: The updated setup version. message UpdateSetupResponse { - // success: description flag of the operation. + // success: Whether the operation succeeded. bool success = 1; // setup: The updated setup entity. Setup setup = 2; + // setup_version: The updated setup version. + SetupVersion setup_version = 3; } // DeleteSetupRequest @@ -211,146 +227,105 @@ message DeleteSetupRequest { } // DeleteSetupResponse -// Indicates that the setup has been successfully deleted. +// Indicates whether the setup has been successfully deleted. +// +// Fields: +// - success: Whether the operation succeeded. message DeleteSetupResponse { - // success: description flag of the operation. + // success: Whether the operation succeeded. bool success = 1; } -// CreateSetupVersionRequest -// This request is used to create a new setup version. +// ChangeVisibilityRequest +// This request is used to change the visibility scope of an existing setup. // // Fields: -// - setup_id: The unique identifier of the parent setup. -// - version: The label for the new version. -// - content: The configuration content for this version. -message CreateSetupVersionRequest { - // setup_id: The unique identifier of the parent setup. +// - setup_id: The unique identifier of the setup. +// - visibility: The new visibility scope for the setup. +message ChangeVisibilityRequest { + // setup_id: The unique identifier of the setup. string setup_id = 1 [(buf.validate.field).required = true]; - // version: The version label (e.g., "v1", "v2"). - string version = 2 [(buf.validate.field).required = true]; - // content: Key-value pairs for configuration content. - google.protobuf.Struct content = 3; + // visibility: The new visibility scope for the setup. + Visibility visibility = 2 [(buf.validate.field).required = true]; } -// CreateSetupVersionResponse -// Returns the newly created setup version status flag. +// ChangeVisibilityResponse +// Returns the setup with its updated visibility. // // Fields: -// - success: description flag of the operation. -// - setup_version: The newly created setup version entity. -message CreateSetupVersionResponse { - // success: description flag of the operation. +// - success: Whether the operation succeeded. +// - setup: The updated setup entity. +// - setup_version: The current setup version. +message ChangeVisibilityResponse { + // success: Whether the operation succeeded. bool success = 1; - // setup_version: The newly created setup version entity. - SetupVersion setup_version = 2; -} - -// GetSetupVersionRequest -// This request is used to retrieve a setup version by its unique identifier. -// -// Fields: -// - setup_version_id: The unique identifier of the setup version. -message GetSetupVersionRequest { - // setup_version_id: The unique identifier of the setup version. - string setup_version_id = 1; + // setup: The updated setup entity. + Setup setup = 2; + // setup_version: The current setup version. + SetupVersion setup_version = 3; } -// GetSetupVersionResponse -// Returns the setup version corresponding to the setup_version_id. +// ListSetupVersionsRequest +// This request is used to list the versions of a setup, most recent first. // // Fields: -// - setup_version: The retrieved setup version entity. -message GetSetupVersionResponse { - // setup_version: The retrieved setup version entity. - SetupVersion setup_version = 1; +// - setup_id: The unique identifier of the setup whose versions are listed. +// - limit: The maximum number of setup versions to return. +// - offset: The number of setup versions to skip for pagination. +message ListSetupVersionsRequest { + // setup_id: The unique identifier of the setup. + string setup_id = 1 [(buf.validate.field).required = true]; + // limit: The maximum number of setup versions to return. + int32 limit = 2 [ + (buf.validate.field).int32.gte = 1, + (buf.validate.field).int32.lte = 1000 + ]; + // offset: The number of setup versions to skip for pagination. + int32 offset = 3 [(buf.validate.field).int32.gte = 0]; } -// SearchSetupVersionsRequest -// This request is used to search for setup versions using filters. +// ListSetupVersionsResponse +// Returns the versions of a setup, ordered by creation date descending. // // Fields: -// - setup_id: (Optional) Filter by the parent setup identifier. -// - version: (Optional) Filter by the version label. -message SearchSetupVersionsRequest { - // setup_id: The unique identifier of the parent setup. - string setup_id = 1; - // version: The version label to filter wirh. - optional string version = 2; -} - -// SearchSetupVersionsResponse -// Returns a list of setup versions that match the search criteria. -message SearchSetupVersionsResponse { - // setup_versions: A list of setup versions matching the criteria. +// - setup_versions: The setup versions matching the request. +// - total_count: The total number of setup versions for this setup. +// - current_setup_version_id: The identifier of the currently active version. +message ListSetupVersionsResponse { + // setup_versions: The setup versions matching the request. repeated SetupVersion setup_versions = 1; + // total_count: The total number of setup versions for this setup. + int32 total_count = 2 [(buf.validate.field).int32.gte = 0]; + // current_setup_version_id: The identifier of the currently active version, empty if none. + string current_setup_version_id = 3; } -// UpdateSetupVersionRequest -// This request is used to update an existing setup version. -// -// Fields: -// - setup_version_id: The unique identifier of the setup version to update. -// - version: (Optional) The new version label. -// - content: (Optional) The new configuration content. -message UpdateSetupVersionRequest { - // setup_version_id: The unique identifier of the setup version to update. - string setup_version_id = 1 [(buf.validate.field).required = true]; - // version: The version label. - string version = 2 [(buf.validate.field).required = true]; - // content: Key-value pairs for configuration content. - google.protobuf.Struct content = 3 [(buf.validate.field).required = true]; -} - -// UpdateSetupVersionResponse -// Returns the updated setup version. +// SetCurrentSetupVersionRequest +// This request is used to activate an existing version of a setup, making it +// the current one. // // Fields: -// - success: description flag of the operation. -// - setup_version: The updated setup version entity. -message UpdateSetupVersionResponse { - // success: description flag of the operation. - bool success = 1; - // setup_version: The updated setup version entity. - SetupVersion setup_version = 2; +// - setup_id: The unique identifier of the setup. +// - setup_version_id: The unique identifier of the setup version to activate. +message SetCurrentSetupVersionRequest { + // setup_id: The unique identifier of the setup. + string setup_id = 1 [(buf.validate.field).required = true]; + // setup_version_id: The unique identifier of the setup version to activate. + string setup_version_id = 2 [(buf.validate.field).required = true]; } -// DeleteSetupVersionRequest -// This request is used to delete a setup version by its unique identifier. +// SetCurrentSetupVersionResponse +// Returns the setup with its newly activated version. // // Fields: -// - setup_version_id: The unique identifier of the setup version to delete. -message DeleteSetupVersionRequest { - // setup_version_id: The unique identifier of the setup version. - string setup_version_id = 1 [(buf.validate.field).required = true]; -} - -// DeleteSetupVersionResponse -// Indicates that the setup version has been successfully deleted. -message DeleteSetupVersionResponse { - // success: description flag of the operation. +// - success: Whether the operation succeeded. +// - setup: The updated setup entity. +// - setup_version: The newly activated setup version. +message SetCurrentSetupVersionResponse { + // success: Whether the operation succeeded. bool success = 1; -} - -// ListSetupsRequest is the request message for listing setups. -message ListSetupsRequest { - // organisation_id: Filter by organisation ID. - optional string organisation_id = 1; - // owner_id: Filter by owner ID. - optional string owner_id = 2; - // limit: Maximum number of setups to return. - int32 limit = 3 [ - (buf.validate.field).int32.gte = 1, - (buf.validate.field).int32.lte = 1000 - ]; - // offset: Number of setups to skip. - int32 offset = 4 [(buf.validate.field).int32.gte = 0]; -} - -// ListSetupsResponse is the response message containing a list of setups. -message ListSetupsResponse { - // setups: List of setups matching the criteria. - repeated Setup setups = 1; - // total_count: Total number of setups matching the criteria. - int32 total_count = 2 [(buf.validate.field).int32.gte = 0]; + // setup: The updated setup entity. + Setup setup = 2; + // setup_version: The newly activated setup version. + SetupVersion setup_version = 3; } diff --git a/proto/agentic_mesh_protocol/setup/v1/setup_service.proto b/proto/agentic_mesh_protocol/setup/v1/setup_service.proto index e9302ef..8199baf 100644 --- a/proto/agentic_mesh_protocol/setup/v1/setup_service.proto +++ b/proto/agentic_mesh_protocol/setup/v1/setup_service.proto @@ -21,25 +21,24 @@ import "agentic_mesh_protocol/setup/v1/setup.proto"; // SetupService // Provides operations for setups and setup versions. service SetupService { - // DEPRECATED: CreateSetup — unused in SDK. - rpc CreateSetup(CreateSetupRequest) returns (CreateSetupResponse); // GetSetup retrieves a setup by its unique identifier. rpc GetSetup(GetSetupRequest) returns (GetSetupResponse); - // DEPRECATED: UpdateSetup — unused in SDK. + + // CreateSetup creates a new setup. + rpc CreateSetup(CreateSetupRequest) returns (CreateSetupResponse); + + // UpdateSetup updates an existing setup. rpc UpdateSetup(UpdateSetupRequest) returns (UpdateSetupResponse); - // DEPRECATED: DeleteSetup — unused in SDK. + + // DeleteSetup deletes a setup by its unique identifier. rpc DeleteSetup(DeleteSetupRequest) returns (DeleteSetupResponse); - // DEPRECATED: CreateSetupVersion — unused in SDK. - rpc CreateSetupVersion(CreateSetupVersionRequest) returns (CreateSetupVersionResponse); - // GetSetupVersion retrieves a setup version by its unique identifier. - rpc GetSetupVersion(GetSetupVersionRequest) returns (GetSetupVersionResponse); - // DEPRECATED: SearchSetupVersions — unused in SDK. - rpc SearchSetupVersions(SearchSetupVersionsRequest) returns (SearchSetupVersionsResponse); - // DEPRECATED: UpdateSetupVersion — unused in SDK. - rpc UpdateSetupVersion(UpdateSetupVersionRequest) returns (UpdateSetupVersionResponse); - // DEPRECATED: DeleteSetupVersion — unused in SDK. - rpc DeleteSetupVersion(DeleteSetupVersionRequest) returns (DeleteSetupVersionResponse); - // DEPRECATED: ListSetups — unused in SDK. - rpc ListSetups(ListSetupsRequest) returns (ListSetupsResponse); + // ChangeVisibility changes the visibility scope of a setup. + rpc ChangeVisibility(ChangeVisibilityRequest) returns (ChangeVisibilityResponse); + + // ListSetupVersions lists the versions of a setup. + rpc ListSetupVersions(ListSetupVersionsRequest) returns (ListSetupVersionsResponse); + + // SetCurrentSetupVersion activates an existing version of a setup. + rpc SetCurrentSetupVersion(SetCurrentSetupVersionRequest) returns (SetCurrentSetupVersionResponse); } diff --git a/proto/agentic_mesh_protocol/storage/v1/data.proto b/proto/agentic_mesh_protocol/storage/v1/data.proto index fb828af..a23938a 100644 --- a/proto/agentic_mesh_protocol/storage/v1/data.proto +++ b/proto/agentic_mesh_protocol/storage/v1/data.proto @@ -34,11 +34,38 @@ enum DataType { OTHER = 4; } +// Visibility: Access scope of a record +enum Visibility { + // VISIBILITY_UNSPECIFIED: Visibility not specified + VISIBILITY_UNSPECIFIED = 0; + // VISIBILITY_PUBLIC: Visible to everyone + VISIBILITY_PUBLIC = 1; + // VISIBILITY_PRIVATE: Visible only to the owner + VISIBILITY_PRIVATE = 2; + // VISIBILITY_INTERNAL: Visible within the organisation + VISIBILITY_INTERNAL = 3; +} + +// ContextStorage: Type of context a record is scoped to. The matching identifier is +// resolved server-side from the task metadata, so it is not carried by the requests. +enum ContextStorage { + // CONTEXT_UNSPECIFIED: Default unspecified context + CONTEXT_UNSPECIFIED = 0; + // CONTEXT_MISSIONS: Context related to missions + CONTEXT_MISSIONS = 1; + // CONTEXT_SETUP_VERSIONS: Context related to setup versions + CONTEXT_SETUP_VERSIONS = 2; + // CONTEXT_USERS: Context related to users + CONTEXT_USERS = 3; + // CONTEXT_ORGANIZATIONS: Context related to organizations + CONTEXT_ORGANIZATIONS = 4; +} + // StorageRecord: Message to represent stored data message StorageRecord { // data: JSON Object to store google.protobuf.Struct data = 1 [(buf.validate.field).required = true]; - // context: Mission ID linked to the data + // context: Prefixed identifier of the context owning the record (missions: or setup_versions:) string context = 2 [ (buf.validate.field).required = true, (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" @@ -53,23 +80,29 @@ message StorageRecord { google.protobuf.Timestamp update_date = 6 [(buf.validate.field).required = true]; // data_type: Type of the data DataType data_type = 7 [(buf.validate.field).required = true]; + // visibility: Access scope of the record + Visibility visibility = 8 [(buf.validate.field).required = true]; + // storage_id: Unique identifier for the storage record + string storage_id = 9 [ + (buf.validate.field).required = true, + (buf.validate.field).string.prefix = "storage:" + ]; } // StoreRecordRequest: Request to store record message StoreRecordRequest { // data: Data to store or to retrieve google.protobuf.Struct data = 1 [(buf.validate.field).required = true]; - // context: Mission ID linked to the data - string context = 2 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" - ]; + // context: Type of context the record is scoped to (identifier resolved server-side) + ContextStorage context = 2 [(buf.validate.field).required = true]; // collection: Name of a group of records (unique by context) string collection = 3 [(buf.validate.field).required = true]; // record_id: Unique identifier for the record within collection string record_id = 4 [(buf.validate.field).required = true]; // data_type: Type of the data DataType data_type = 5 [(buf.validate.field).required = true]; + // visibility: Access scope of the record (optional; defaults server-side) + Visibility visibility = 6; } // StoreRecordResponse: Response to stored record @@ -82,15 +115,14 @@ message StoreRecordResponse { // ReadRecordRequest: Request to read a record message ReadRecordRequest { - // context: Mission ID linked to the data - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" - ]; + // context: Type of context the record is scoped to (identifier resolved server-side) + ContextStorage context = 1 [(buf.validate.field).required = true]; // collection: Name of a group of records (unique by context) string collection = 2 [(buf.validate.field).required = true]; // record_id: Unique identifier for the record within collection string record_id = 3 [(buf.validate.field).required = true]; + // storage_id: Unique identifier for the storage record (optional; defaults server-side) + string storage_id = 4 [(buf.validate.field).string.prefix = "storage:"]; } // ReadRecordResponse: Response after read a record @@ -105,15 +137,14 @@ message ReadRecordResponse { message UpdateRecordRequest { // data: Data to store or to retrieve google.protobuf.Struct data = 1 [(buf.validate.field).required = true]; - // context: Mission ID linked to the data - string context = 2 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" - ]; + // context: Type of context the record is scoped to (identifier resolved server-side) + ContextStorage context = 2 [(buf.validate.field).required = true]; // collection: Name of a group of records (unique by context) string collection = 3 [(buf.validate.field).required = true]; // record_id: Unique identifier for the record within collection string record_id = 4 [(buf.validate.field).required = true]; + // visibility: Access scope of the record (optional; defaults server-side) + Visibility visibility = 5; } // UpdateRecordResponse: Response to record modification @@ -126,12 +157,9 @@ message UpdateRecordResponse { // RemoveRecordRequest: Request to remove a record message RemoveRecordRequest { - // context: Mission ID linked to the data - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" - ]; - // collection: Name of a group of records (unique by mission_id) + // context: Type of context the record is scoped to (identifier resolved server-side) + ContextStorage context = 1 [(buf.validate.field).required = true]; + // collection: Name of a group of records (unique by context) string collection = 2 [(buf.validate.field).required = true]; // record_id: Unique identifier for the record within collection string record_id = 3 [(buf.validate.field).required = true]; @@ -145,13 +173,21 @@ message RemoveRecordResponse { // ListRecordsRequest: Request to list all records in a given collection message ListRecordsRequest { - // context: Mission ID linked to the data - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions|users|organizations):.+" - ]; + // context: Type of context the records are scoped to (identifier resolved server-side) + ContextStorage context = 1 [(buf.validate.field).required = true]; // collection: Name of a group of records (unique by context) string collection = 2 [(buf.validate.field).required = true]; + // visibilities: Filter by visibility (empty = no filter) + repeated Visibility visibilities = 3 [(buf.validate.field).repeated.items.enum.not_in = 0]; + // record_id: Filter by record identifier within collection (optional; empty = no filter) + string record_id = 4; + // limit: Maximum number of records to return (0 = server default of 20, capped at 100) + int32 limit = 5 [ + (buf.validate.field).int32.gte = 0, + (buf.validate.field).int32.lte = 100 + ]; + // offset: Number of records to skip before returning results + int32 offset = 6 [(buf.validate.field).int32.gte = 0]; } // ListRecordsResponse: Response to list all records in a given collection @@ -162,13 +198,12 @@ message ListRecordsResponse { // RemoveCollectionRequest: Request to remove a collection message RemoveCollectionRequest { - // context: Mission ID linked to the data - string context = 1 [ - (buf.validate.field).required = true, - (buf.validate.field).string.pattern = "^(missions|setup_versions):.+" - ]; + // context: Type of context the record is scoped to (identifier resolved server-side) + ContextStorage context = 1 [(buf.validate.field).required = true]; // collection: Name of a group of records (unique by context) string collection = 2 [(buf.validate.field).required = true]; + // record_id: Restrict removal to this record identifier (optional; empty = whole collection) + string record_id = 3; } // RemoveCollectionResponse: Response to removed collection diff --git a/proto/agentic_mesh_protocol/storage/v1/storage_service.proto b/proto/agentic_mesh_protocol/storage/v1/storage_service.proto index b35e6f3..1bb6e28 100644 --- a/proto/agentic_mesh_protocol/storage/v1/storage_service.proto +++ b/proto/agentic_mesh_protocol/storage/v1/storage_service.proto @@ -32,7 +32,7 @@ service StorageService { // RemoveRecord: Delete a record from storage rpc RemoveRecord(RemoveRecordRequest) returns (RemoveRecordResponse); - // DEPRECATED: ListRecords — unused in SDK, no callers. + // ListRecords: List records in a collection, optionally filtered by visibility rpc ListRecords(ListRecordsRequest) returns (ListRecordsResponse); // DEPRECATED: RemoveCollection — unused in SDK, no callers. 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..f6f97c3 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,9 @@ 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