snakepit

syntax = "proto3";

package snakepit.bridge;

import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";

service BridgeService {
  // Health & Session Management
  rpc Ping(PingRequest) returns (PingResponse);
  rpc InitializeSession(InitializeSessionRequest) returns (InitializeSessionResponse);
  rpc CleanupSession(CleanupSessionRequest) returns (CleanupSessionResponse);
  rpc GetSession(GetSessionRequest) returns (GetSessionResponse);
  rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);

  // Tool Execution
  rpc ExecuteTool(ExecuteToolRequest) returns (ExecuteToolResponse);
  rpc ExecuteStreamingTool(ExecuteToolRequest) returns (stream ToolChunk);

  // Tool Registration & Discovery
  rpc RegisterTools(RegisterToolsRequest) returns (RegisterToolsResponse);
  rpc GetExposedElixirTools(GetExposedElixirToolsRequest) returns (GetExposedElixirToolsResponse);
  rpc ExecuteElixirTool(ExecuteElixirToolRequest) returns (ExecuteElixirToolResponse);

  // Telemetry Stream (bidirectional)
  rpc StreamTelemetry(stream TelemetryControl) returns (stream TelemetryEvent);
}

// Core Messages
message PingRequest {
  string message = 1;
}

message PingResponse {
  string message = 1;
  google.protobuf.Timestamp server_time = 2;
}

message InitializeSessionRequest {
  string session_id = 1;
  map<string, string> metadata = 2;
  SessionConfig config = 3;
}

message SessionConfig {
  bool enable_caching = 1;
  int32 cache_ttl_seconds = 2;
  bool enable_telemetry = 3;
}

message InitializeSessionResponse {
  bool success = 1;
  string error_message = 2;
  map<string, ToolSpec> available_tools = 3;
}

message CleanupSessionRequest {
  string session_id = 1;
  bool force = 2;
}

message CleanupSessionResponse {
  bool success = 1;
  int32 resources_cleaned = 2;
}

// Tool Messages
message ToolSpec {
  string name = 1;
  string description = 2;
  repeated ParameterSpec parameters = 3;
  map<string, string> metadata = 4;
  bool supports_streaming = 5;
}

message ParameterSpec {
  string name = 1;
  string type = 2;
  string description = 3;
  bool required = 4;
  google.protobuf.Any default_value = 5;
  string validation_json = 6;
}

message ExecuteToolRequest {
  string session_id = 1;
  string tool_name = 2;
  map<string, google.protobuf.Any> parameters = 3;
  map<string, string> metadata = 4;
  bool stream = 5;

  // Binary parameters for large data (e.g., images, audio, video)
  // Keys should match parameter names, metadata should describe format
  map<string, bytes> binary_parameters = 6;
}

message ExecuteToolResponse {
  bool success = 1;
  google.protobuf.Any result = 2;
  string error_message = 3;
  map<string, string> metadata = 4;
  int64 execution_time_ms = 5;
  // Optional opaque binary result payload for large or non-JSON-friendly data
  bytes binary_result = 6;
}

message ToolChunk {
  string chunk_id = 1;
  bytes data = 2;
  bool is_final = 3;
  map<string, string> metadata = 4;
}

// Session Management Messages
message GetSessionRequest {
  string session_id = 1;
}

message GetSessionResponse {
  string session_id = 1;
  map<string, string> metadata = 2;
  google.protobuf.Timestamp created_at = 3;
  int32 tool_count = 4;
}

message HeartbeatRequest {
  string session_id = 1;
  google.protobuf.Timestamp client_time = 2;
}

message HeartbeatResponse {
  google.protobuf.Timestamp server_time = 1;
  bool session_valid = 2;
}

// Tool Registration & Discovery Messages
message RegisterToolsRequest {
  string session_id = 1;
  repeated ToolRegistration tools = 2;
  string worker_id = 3;
}

message ToolRegistration {
  string name = 1;
  string description = 2;
  repeated ParameterSpec parameters = 3;
  map<string, string> metadata = 4;
  bool supports_streaming = 5;
}

message RegisterToolsResponse {
  bool success = 1;
  map<string, string> tool_ids = 2;
  string error_message = 3;
}

message GetExposedElixirToolsRequest {
  string session_id = 1;
}

message GetExposedElixirToolsResponse {
  repeated ToolSpec tools = 1;
}

message ExecuteElixirToolRequest {
  string session_id = 1;
  string tool_name = 2;
  map<string, google.protobuf.Any> parameters = 3;
  map<string, string> metadata = 4;
}

message ExecuteElixirToolResponse {
  bool success = 1;
  google.protobuf.Any result = 2;
  string error_message = 3;
  map<string, string> metadata = 4;
  int64 execution_time_ms = 5;
  // Optional opaque binary result payload for Elixir tools
  bytes binary_result = 6;
}

// Telemetry Messages
message TelemetryEvent {
  repeated string event_parts = 1;               // e.g., ["python", "call", "start"]
  map<string, TelemetryValue> measurements = 2;  // numeric/categorical values
  map<string, string> metadata = 3;              // contextual data (string keys)
  int64 timestamp_ns = 4;                        // unix epoch, nanoseconds
  string correlation_id = 5;                     // optional tracing correlation
}

message TelemetryValue {
  oneof value {
    int64 int_value = 1;
    double float_value = 2;
    string string_value = 3;
  }
}

message TelemetryControl {
  oneof control {
    TelemetryToggle toggle = 1;
    TelemetrySamplingUpdate sampling = 2;
    TelemetryEventFilter filter = 3;
  }
}

message TelemetryToggle {
  bool enabled = 1;
}

message TelemetrySamplingUpdate {
  double sampling_rate = 1;               // 0.0 ≤ rate ≤ 1.0
  repeated string event_patterns = 2;     // glob-style patterns (e.g. "python.*")
}

message TelemetryEventFilter {
  repeated string allow = 1;              // explicit whitelist
  repeated string deny = 2;               // explicit blacklist
}