From 2809b23f692d82afaaaa629be892f65ad0367d99 Mon Sep 17 00:00:00 2001 From: Vitalii Valkov Date: Tue, 1 Sep 2026 08:00:06 +0400 Subject: [PATCH 1/4] App configuration schema Apps report a JSON Schema for their installation configuration so the Console can build a form instead of offering a JSON editor. - App.configuration_schema / schema_reported_at - Installation.secret_keys_set - ReportConfigurationSchema, exposed on AppsGateway alongside GetInstallationConfiguration - Agents.ResolveAgentExists / ResolveEnvironmentExists and LLM.ResolveModelExists, for validating x-agyn-ref properties --- proto/agynio/api/agents/v1/agents.proto | 24 ++++++++++++++++++++++++ proto/agynio/api/apps/v1/apps.proto | 23 +++++++++++++++++++++++ proto/agynio/api/gateway/v1/apps.proto | 2 ++ proto/agynio/api/llm/v1/llm.proto | 13 +++++++++++++ 4 files changed, 62 insertions(+) diff --git a/proto/agynio/api/agents/v1/agents.proto b/proto/agynio/api/agents/v1/agents.proto index efa8f3b..fb65be1 100644 --- a/proto/agynio/api/agents/v1/agents.proto +++ b/proto/agynio/api/agents/v1/agents.proto @@ -148,6 +148,30 @@ service AgentsService { } rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); + + // --- Internal reference checks --- + // Verify a resource exists in an organization, for another service + // validating a reference before it is persisted. + rpc ResolveAgentExists(ResolveAgentExistsRequest) returns (ResolveAgentExistsResponse); + rpc ResolveEnvironmentExists(ResolveEnvironmentExistsRequest) returns (ResolveEnvironmentExistsResponse); +} + +message ResolveAgentExistsRequest { + string agent_id = 1; + string organization_id = 2; +} + +message ResolveAgentExistsResponse { + bool exists = 1; +} + +message ResolveEnvironmentExistsRequest { + string environment_id = 1; + string organization_id = 2; +} + +message ResolveEnvironmentExistsResponse { + bool exists = 1; } // =========================================================================== diff --git a/proto/agynio/api/apps/v1/apps.proto b/proto/agynio/api/apps/v1/apps.proto index 7ac79b8..9cab19b 100644 --- a/proto/agynio/api/apps/v1/apps.proto +++ b/proto/agynio/api/apps/v1/apps.proto @@ -48,6 +48,9 @@ service AppsService { rpc ListInstallationAuditLogEntries(ListInstallationAuditLogEntriesRequest) returns (ListInstallationAuditLogEntriesResponse); rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); + + // Replace the app's configuration schema with the reported document. + rpc ReportConfigurationSchema(ReportConfigurationSchemaRequest) returns (ReportConfigurationSchemaResponse); } message EntityMeta { @@ -74,6 +77,12 @@ message App { string organization_id = 9; AppVisibility visibility = 10; repeated string permissions = 11; + // JSON Schema for installation configuration. Root is an object with a flat + // properties map; property types are string, integer, number, boolean, and + // array of string. Absent until the app first reports one. + optional google.protobuf.Struct configuration_schema = 12; + // When configuration_schema was last reported. Absent while it is. + optional google.protobuf.Timestamp schema_reported_at = 13; } message AppProfile { @@ -89,8 +98,13 @@ message Installation { string app_id = 2; string organization_id = 3; string slug = 4; + // Properties marked x-agyn-secret in the app's configuration_schema are + // omitted here on every read path except GetInstallationConfiguration. google.protobuf.Struct configuration = 5; optional string status = 6; + // Names of the x-agyn-secret properties that hold a value. Set on the read + // paths where those values are omitted. + repeated string secret_keys_set = 7; } enum InstallationAuditLogLevel { @@ -272,6 +286,15 @@ message GetInstallationConfigurationResponse { google.protobuf.Struct configuration = 1; } +message ReportConfigurationSchemaRequest { + string app_id = 1; + google.protobuf.Struct configuration_schema = 2; +} + +message ReportConfigurationSchemaResponse { + App app = 1; +} + message ReportInstallationStatusRequest { string installation_id = 1; string status = 2; diff --git a/proto/agynio/api/gateway/v1/apps.proto b/proto/agynio/api/gateway/v1/apps.proto index 4e78b61..189bb3c 100644 --- a/proto/agynio/api/gateway/v1/apps.proto +++ b/proto/agynio/api/gateway/v1/apps.proto @@ -24,4 +24,6 @@ service AppsGateway { rpc ReportInstallationStatus(agynio.api.apps.v1.ReportInstallationStatusRequest) returns (agynio.api.apps.v1.ReportInstallationStatusResponse); rpc AppendInstallationAuditLogEntry(agynio.api.apps.v1.AppendInstallationAuditLogEntryRequest) returns (agynio.api.apps.v1.AppendInstallationAuditLogEntryResponse); rpc ListInstallationAuditLogEntries(agynio.api.apps.v1.ListInstallationAuditLogEntriesRequest) returns (agynio.api.apps.v1.ListInstallationAuditLogEntriesResponse); + rpc GetInstallationConfiguration(agynio.api.apps.v1.GetInstallationConfigurationRequest) returns (agynio.api.apps.v1.GetInstallationConfigurationResponse); + rpc ReportConfigurationSchema(agynio.api.apps.v1.ReportConfigurationSchemaRequest) returns (agynio.api.apps.v1.ReportConfigurationSchemaResponse); } diff --git a/proto/agynio/api/llm/v1/llm.proto b/proto/agynio/api/llm/v1/llm.proto index 589f360..65303ee 100644 --- a/proto/agynio/api/llm/v1/llm.proto +++ b/proto/agynio/api/llm/v1/llm.proto @@ -47,6 +47,19 @@ service LLMService { rpc CountSubscriptionsReferencingSecret(CountSubscriptionsReferencingSecretRequest) returns (CountSubscriptionsReferencingSecretResponse); rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); + + // Verify a model exists in an organization, for another service validating a + // reference before it is persisted. + rpc ResolveModelExists(ResolveModelExistsRequest) returns (ResolveModelExistsResponse); +} + +message ResolveModelExistsRequest { + string model_id = 1; + string organization_id = 2; +} + +message ResolveModelExistsResponse { + bool exists = 1; } // =========================================================================== From dcfbce3d0b7f957c3b01fef6d5006a0b783f7953 Mon Sep 17 00:00:00 2001 From: Vitalii Valkov Date: Tue, 1 Sep 2026 08:10:06 +0400 Subject: [PATCH 2/4] Per-property configuration validation errors --- proto/agynio/api/apps/v1/apps.proto | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/proto/agynio/api/apps/v1/apps.proto b/proto/agynio/api/apps/v1/apps.proto index 9cab19b..56d4845 100644 --- a/proto/agynio/api/apps/v1/apps.proto +++ b/proto/agynio/api/apps/v1/apps.proto @@ -286,6 +286,17 @@ message GetInstallationConfigurationResponse { google.protobuf.Struct configuration = 1; } +// ConfigurationValidationFailure is attached as an error detail when a +// configuration is rejected, naming each property that failed. +message ConfigurationValidationFailure { + repeated ConfigurationPropertyError errors = 1; +} + +message ConfigurationPropertyError { + string property = 1; + string message = 2; +} + message ReportConfigurationSchemaRequest { string app_id = 1; google.protobuf.Struct configuration_schema = 2; From 66c369e557d1d8ad64da0c4076398e94abc1e327 Mon Sep 17 00:00:00 2001 From: Vitalii Valkov Date: Sat, 12 Sep 2026 18:41:08 +0200 Subject: [PATCH 3/4] Drop secret_keys_set x-agyn-secret marks a property for masking in the UI, not for redaction on the wire. Hiding a value the API still stores and returns elsewhere is a claim the platform cannot keep; secrets belong in the Secrets service, and that is a separate change. --- proto/agynio/api/apps/v1/apps.proto | 5 ----- 1 file changed, 5 deletions(-) diff --git a/proto/agynio/api/apps/v1/apps.proto b/proto/agynio/api/apps/v1/apps.proto index 56d4845..f92f994 100644 --- a/proto/agynio/api/apps/v1/apps.proto +++ b/proto/agynio/api/apps/v1/apps.proto @@ -98,13 +98,8 @@ message Installation { string app_id = 2; string organization_id = 3; string slug = 4; - // Properties marked x-agyn-secret in the app's configuration_schema are - // omitted here on every read path except GetInstallationConfiguration. google.protobuf.Struct configuration = 5; optional string status = 6; - // Names of the x-agyn-secret properties that hold a value. Set on the read - // paths where those values are omitted. - repeated string secret_keys_set = 7; } enum InstallationAuditLogLevel { From 40bf23f935efd57d1ad759debf73c5836dc91720 Mon Sep 17 00:00:00 2001 From: Vitalii Valkov Date: Mon, 14 Sep 2026 12:45:50 +0200 Subject: [PATCH 4/4] Keep service behaviour out of the proto comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The comments described when a field is populated, what a method does to stored state, and why another service calls it. None of that is the interface — it is the Apps Service's behaviour, it belongs in the architecture repo, and a copy here is one that goes stale without anyone noticing. What is left states shape and constraints: the schema document is an object with a flat properties map and these property types. --- proto/agynio/api/agents/v1/agents.proto | 3 --- proto/agynio/api/apps/v1/apps.proto | 6 +----- proto/agynio/api/llm/v1/llm.proto | 2 -- 3 files changed, 1 insertion(+), 10 deletions(-) diff --git a/proto/agynio/api/agents/v1/agents.proto b/proto/agynio/api/agents/v1/agents.proto index fb65be1..e6dee3f 100644 --- a/proto/agynio/api/agents/v1/agents.proto +++ b/proto/agynio/api/agents/v1/agents.proto @@ -149,9 +149,6 @@ service AgentsService { rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); - // --- Internal reference checks --- - // Verify a resource exists in an organization, for another service - // validating a reference before it is persisted. rpc ResolveAgentExists(ResolveAgentExistsRequest) returns (ResolveAgentExistsResponse); rpc ResolveEnvironmentExists(ResolveEnvironmentExistsRequest) returns (ResolveEnvironmentExistsResponse); } diff --git a/proto/agynio/api/apps/v1/apps.proto b/proto/agynio/api/apps/v1/apps.proto index f92f994..6256858 100644 --- a/proto/agynio/api/apps/v1/apps.proto +++ b/proto/agynio/api/apps/v1/apps.proto @@ -49,7 +49,6 @@ service AppsService { rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); - // Replace the app's configuration schema with the reported document. rpc ReportConfigurationSchema(ReportConfigurationSchemaRequest) returns (ReportConfigurationSchemaResponse); } @@ -79,9 +78,8 @@ message App { repeated string permissions = 11; // JSON Schema for installation configuration. Root is an object with a flat // properties map; property types are string, integer, number, boolean, and - // array of string. Absent until the app first reports one. + // array of string. optional google.protobuf.Struct configuration_schema = 12; - // When configuration_schema was last reported. Absent while it is. optional google.protobuf.Timestamp schema_reported_at = 13; } @@ -281,8 +279,6 @@ message GetInstallationConfigurationResponse { google.protobuf.Struct configuration = 1; } -// ConfigurationValidationFailure is attached as an error detail when a -// configuration is rejected, naming each property that failed. message ConfigurationValidationFailure { repeated ConfigurationPropertyError errors = 1; } diff --git a/proto/agynio/api/llm/v1/llm.proto b/proto/agynio/api/llm/v1/llm.proto index 65303ee..90f54ce 100644 --- a/proto/agynio/api/llm/v1/llm.proto +++ b/proto/agynio/api/llm/v1/llm.proto @@ -48,8 +48,6 @@ service LLMService { rpc DeleteOrganizationResources(DeleteOrganizationResourcesRequest) returns (DeleteOrganizationResourcesResponse); - // Verify a model exists in an organization, for another service validating a - // reference before it is persisted. rpc ResolveModelExists(ResolveModelExistsRequest) returns (ResolveModelExistsResponse); }