Fix #63: Improve protobuf/gRPC definitions with industry best practices

Author: orpiske

capabilities-archetypes/capabilities-archetypes-java-tool/src/main/resources/archetype-resources/src/main/java/AppTool.java

@@ -1,8 +1,9 @@
 package ${package};
 
-import ai.wanaku.core.exchange.ToolInvokeReply;
-import ai.wanaku.core.exchange.ToolInvokeRequest;
-import ai.wanaku.core.exchange.ToolInvokerGrpc;
+import ai.wanaku.core.exchange.v1.ToolInvokeReply;
+import ai.wanaku.core.exchange.v1.ToolInvokeRequest;
+import ai.wanaku.core.exchange.v1.ToolInvokerGrpc;
+import io.grpc.Status;
 import io.grpc.stub.StreamObserver;
 import java.util.List;
 import java.util.Map;
@@ -29,12 +30,13 @@ public void invokeTool(ToolInvokeRequest request, StreamObserver<ToolInvokeReply
             // Build the response
             responseObserver.onNext(
                     ToolInvokeReply.newBuilder()
-                            .setIsError(false)
                             .addAllContent(List.of(response.toString())).build());
 
             responseObserver.onCompleted();
-        } finally {
-            // cleanup
+        } catch (Exception e) {
+            responseObserver.onError(Status.INTERNAL
+                    .withDescription(String.format("Unable to invoke tool: %s", e.getMessage()))
+                    .asRuntimeException());
         }
     }
-}
+}

capabilities-archetypes/capabilities-archetypes-java-tool/src/main/resources/archetype-resources/src/main/java/ProvisionBase.java

@@ -4,10 +4,10 @@
 import ai.wanaku.capabilities.sdk.config.provider.api.ProvisionedConfig;
 import ai.wanaku.capabilities.sdk.runtime.provisioners.FileProvisionerLoader;
 import ai.wanaku.capabilities.sdk.util.ProvisioningHelper;
-import ai.wanaku.core.exchange.PropertySchema;
-import ai.wanaku.core.exchange.ProvisionReply;
-import ai.wanaku.core.exchange.ProvisionRequest;
-import ai.wanaku.core.exchange.ProvisionerGrpc;
+import ai.wanaku.core.exchange.v1.PropertySchema;
+import ai.wanaku.core.exchange.v1.ProvisionReply;
+import ai.wanaku.core.exchange.v1.ProvisionRequest;
+import ai.wanaku.core.exchange.v1.ProvisionerGrpc;
 import io.grpc.stub.StreamObserver;
 import java.util.Map;
 

capabilities-exchange/src/main/java/ai/wanaku/capabilities/sdk/util/ProvisioningHelper.java

@@ -3,9 +3,9 @@
 import java.net.URI;
 import ai.wanaku.capabilities.sdk.config.provider.api.ConfigProvisioner;
 import ai.wanaku.capabilities.sdk.config.provider.api.ProvisionedConfig;
-import ai.wanaku.core.exchange.Configuration;
-import ai.wanaku.core.exchange.ProvisionRequest;
-import ai.wanaku.core.exchange.Secret;
+import ai.wanaku.core.exchange.v1.Configuration;
+import ai.wanaku.core.exchange.v1.ProvisionRequest;
+import ai.wanaku.core.exchange.v1.Secret;
 
 /**
  * Helper class for provisioning configurations and secrets.

capabilities-exchange/src/main/proto/codeexecution.proto

@@ -1,10 +1,12 @@
 syntax = "proto3";
 
+import "google/protobuf/timestamp.proto";
+
 option java_multiple_files = true;
-option java_package = "ai.wanaku.core.exchange";
+option java_package = "ai.wanaku.core.exchange.v1";
 option java_outer_classname = "CodeExecutionExchange";
 
-package codeexecution;
+package ai.wanaku.codeexecution.v1;
 
 /**
  * The code execution service definition.
@@ -51,20 +53,20 @@ message CodeExecutionRequest {
    * Optional URI reference to configuration data.
    * Used to provide additional configuration for the execution environment.
    */
-  string configurationURI = 5;
+  string configuration_uri = 5;
 
   /**
    * Optional URI reference to secrets data.
    * Used to provide secure credentials or sensitive data needed for execution.
    */
-  string secretsURI = 6;
+  string secrets_uri = 6;
 
   /**
    * Optional timeout in milliseconds.
    * Maximum time allowed for code execution before termination.
    * If not specified, a default timeout will be applied.
    */
-  int64 timeout = 7;
+  optional int64 timeout = 7;
 
   /**
    * Optional map of environment variables.
@@ -79,11 +81,8 @@ message CodeExecutionRequest {
  * Multiple messages may be sent for a single execution request.
  */
 message CodeExecutionReply {
-  /**
-   * Indicates whether this message represents an error condition.
-   * true if the execution encountered an error, false otherwise.
-   */
-  bool isError = 1;
+  reserved 1;
+  reserved "isError";
 
   /**
    * The execution output content.
@@ -97,7 +96,7 @@ message CodeExecutionReply {
    * The type of output this reply represents.
    * Indicates whether this is stdout, stderr, or a status message.
    */
-  OutputType outputType = 3;
+  OutputType output_type = 3;
 
   /**
    * The current execution status.
@@ -110,71 +109,80 @@ message CodeExecutionReply {
    * Only present in the final message when execution completes.
    * A value of 0 typically indicates successful execution.
    */
-  int32 exitCode = 5;
+  optional int32 exit_code = 5;
 
   /**
    * Optional timestamp when this output was generated.
-   * Unix timestamp in milliseconds since epoch.
    */
-  int64 timestamp = 6;
+  google.protobuf.Timestamp timestamp = 6;
 }
 
 /**
  * Enumeration of output types for code execution replies.
  */
 enum OutputType {
+  /**
+   * Unspecified output type.
+   */
+  OUTPUT_TYPE_UNSPECIFIED = 0;
+
   /**
    * Standard output (stdout) from the executed code.
    */
-  STDOUT = 0;
+  OUTPUT_TYPE_STDOUT = 1;
 
   /**
    * Standard error (stderr) from the executed code.
    */
-  STDERR = 1;
+  OUTPUT_TYPE_STDERR = 2;
 
   /**
    * Status or informational message about execution progress.
    */
-  STATUS = 2;
+  OUTPUT_TYPE_STATUS = 3;
 
   /**
    * Final completion message indicating execution has finished.
    */
-  COMPLETION = 3;
+  OUTPUT_TYPE_COMPLETION = 4;
 }
 
 /**
  * Enumeration of execution status values.
  */
 enum ExecutionStatus {
+  /**
+   * Unspecified execution status.
+   */
+  EXECUTION_STATUS_UNSPECIFIED = 0;
+
   /**
    * Execution is pending and has not yet started.
    */
-  PENDING = 0;
+  EXECUTION_STATUS_PENDING = 1;
 
   /**
    * Code is currently being executed.
    */
-  RUNNING = 1;
+  EXECUTION_STATUS_RUNNING = 2;
 
   /**
    * Execution completed successfully.
    */
-  COMPLETED = 2;
+  EXECUTION_STATUS_COMPLETED = 3;
 
   /**
    * Execution failed with an error.
    */
-  FAILED = 3;
+  EXECUTION_STATUS_FAILED = 4;
 
   /**
    * Execution was cancelled by the client.
    */
-  CANCELLED = 4;
+  EXECUTION_STATUS_CANCELLED = 5;
 
   /**
    * Execution exceeded the timeout limit.
    */
-  TIMEOUT = 5;
+  EXECUTION_STATUS_TIMEOUT = 6;
 }

capabilities-exchange/src/main/proto/healthprobe.proto

@@ -1,10 +1,10 @@
 syntax = "proto3";
 
 option java_multiple_files = true;
-option java_package = "ai.wanaku.core.exchange";
+option java_package = "ai.wanaku.core.exchange.v1";
 option java_outer_classname = "HealthProbeExchange";
 
-package health;
+package ai.wanaku.health.v1;
 
 // The health probe service definition.
 service HealthProbe {
@@ -19,10 +19,30 @@ message HealthProbeRequest {
 
 // The runtime status of the capability
 enum RuntimeStatus {
-  STOPPED = 0;
-  STOPPING = 1;
-  STARTING = 2;
-  STARTED = 3;
+  /**
+   * Unspecified runtime status.
+   */
+  RUNTIME_STATUS_UNSPECIFIED = 0;
+
+  /**
+   * The capability is stopped.
+   */
+  RUNTIME_STATUS_STOPPED = 1;
+
+  /**
+   * The capability is stopping.
+   */
+  RUNTIME_STATUS_STOPPING = 2;
+
+  /**
+   * The capability is starting.
+   */
+  RUNTIME_STATUS_STARTING = 3;
+
+  /**
+   * The capability is started.
+   */
+  RUNTIME_STATUS_STARTED = 4;
 }
 
 // The health probe response message

capabilities-exchange/src/main/proto/provision.proto

@@ -1,14 +1,14 @@
 syntax = "proto3";
 
 option java_multiple_files = true;
-option java_package = "ai.wanaku.core.exchange";
+option java_package = "ai.wanaku.core.exchange.v1";
 option java_outer_classname = "ProvisionExchange";
 
-package tool;
+package ai.wanaku.provision.v1;
 
-// The inquirer exchange service definition.
+// The provisioner service definition.
 service Provisioner {
-  // Invokes a tool
+  // Provisions configuration and secrets
   rpc Provision (ProvisionRequest) returns (ProvisionReply) {}
 }
 
@@ -17,12 +17,20 @@ service Provisioner {
  * itself, etc
  */
 enum PayloadType {
-  REFERENCE = 0;
+  /**
+   * Unspecified payload type.
+   */
+  PAYLOAD_TYPE_UNSPECIFIED = 0;
+
+  /**
+   * A reference to an external configuration or secret.
+   */
+  PAYLOAD_TYPE_REFERENCE = 1;
 
   /**
-   * Invokes tools
+   * A built-in configuration or secret payload.
    */
-  BUILTIN = 1;
+  PAYLOAD_TYPE_BUILTIN = 2;
 }
 
 // Represents a configuration reference
@@ -52,9 +60,9 @@ message PropertySchema {
   bool required = 3;
 }
 
-// The invocation response message
+// The provision response message
 message ProvisionReply {
-  string configurationUri = 1;
-  string secretUri = 2;
+  string configuration_uri = 1;
+  string secret_uri = 2;
   map<string, PropertySchema> properties = 3;
-}
+}

capabilities-exchange/src/main/proto/resourcerequest.proto

@@ -1,29 +1,30 @@
 syntax = "proto3";
 
 option java_multiple_files = true;
-option java_package = "ai.wanaku.core.exchange";
+option java_package = "ai.wanaku.core.exchange.v1";
 option java_outer_classname = "ResourceExchange";
 
-package resource;
+package ai.wanaku.resource.v1;
 
-// The tool exchange service definition.
+// The resource exchange service definition.
 service ResourceAcquirer {
-  // Invokes a tool
+  // Acquires a resource
   rpc ResourceAcquire (ResourceRequest) returns (ResourceReply) {}
 }
 
-// The invocation request message
+// The resource request message
 message ResourceRequest {
   string location = 1;
   string type = 2;
   string name = 3;
   map<string, string> params = 4;
-  string configurationURI = 5;
-  string secretsURI = 6;
+  string configuration_uri = 5;
+  string secrets_uri = 6;
 }
 
-// The invocation response message
+// The resource response message
 message ResourceReply {
-  bool isError = 1;
+  reserved 1;
+  reserved "isError";
   repeated string content = 2;
-}
+}

capabilities-exchange/src/main/proto/toolrequest.proto

@@ -1,10 +1,10 @@
 syntax = "proto3";
 
 option java_multiple_files = true;
-option java_package = "ai.wanaku.core.exchange";
+option java_package = "ai.wanaku.core.exchange.v1";
 option java_outer_classname = "ToolExchange";
 
-package tool;
+package ai.wanaku.tool.v1;
 
 // The tool exchange service definition.
 service ToolInvoker {
@@ -17,13 +17,14 @@ message ToolInvokeRequest {
   string uri = 1;
   string body = 2;
   map<string, string> arguments = 3;
-  string configurationURI = 4;
-  string secretsURI = 5;
+  string configuration_uri = 4;
+  string secrets_uri = 5;
   map<string, string> headers = 6;
 }
 
 // The invocation response message
 message ToolInvokeReply {
-  bool isError = 1;
+  reserved 1;
+  reserved "isError";
   repeated string content = 2;
-}
+}