Comprehensive gRPC Proto Schemas for OODA Agents and Activity Streaming

Objective

Define comprehensive gRPC proto schemas for OODA agent coordination, activity streaming, and inter-agent communication to standardize all gRPC interfaces across the OSSA ecosystem.

Scope

1. agent_communication.proto - Agent-to-agent capability invocation
2. activity_stream.proto - Activity event streaming
3. ooda_coordination.proto - OODA cycle coordination
4. mesh_observer.proto - Mesh topology and observations
5. semantic_analysis.proto - Conversation semantic analysis

Proto Definitions

1. Agent Communication Proto

// proto/agent_communication.proto
syntax = "proto3";

package ossa.agent;

option go_package = "github.com/ossa/agent-protocol/proto/agent";

// Agent Service for capability invocation
service AgentService {
  // Invoke agent capability (unary RPC)
  rpc InvokeCapability(CapabilityRequest) returns (CapabilityResponse);
  
  // Stream capability results (server streaming)
  rpc StreamCapability(CapabilityRequest) returns (stream CapabilityChunk);
  
  // Bidirectional streaming for long-running capabilities
  rpc StreamCapabilityBidi(stream CapabilityRequest) returns (stream CapabilityChunk);
  
  // Health check
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  
  // List available capabilities
  rpc ListCapabilities(ListCapabilitiesRequest) returns (ListCapabilitiesResponse);
}

message CapabilityRequest {
  string agent_id = 1;
  string capability = 2;
  string input = 3;  // JSON-serialized input
  map<string, string> metadata = 4;
  Context context = 5;
}

message CapabilityResponse {
  string output = 1;  // JSON-serialized output
  int32 status_code = 2;
  string error = 3;
  map<string, string> metadata = 4;
}

message CapabilityChunk {
  string data = 1;
  bool is_final = 2;
  int32 chunk_index = 3;
}

message Context {
  string conversation_id = 1;
  string trace_id = 2;
  string session_id = 3;
  string parent_span_id = 4;
  string user_id = 5;
  map<string, string> attributes = 6;
}

message HealthCheckRequest {}

message HealthCheckResponse {
  enum Status {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
  }
  Status status = 1;
  string message = 2;
}

message ListCapabilitiesRequest {}

message ListCapabilitiesResponse {
  repeated Capability capabilities = 1;
}

message Capability {
  string name = 1;
  string description = 2;
  string input_schema = 3;  // JSON Schema
  string output_schema = 4; // JSON Schema
  int32 timeout_seconds = 5;
  bool supports_streaming = 6;
}

2. Activity Stream Proto

// proto/activity_stream.proto
syntax = "proto3";

package ossa.activity;

option go_package = "github.com/ossa/agent-protocol/proto/activity";

// Activity Stream Service
service ActivityStreamService {
  // Bidirectional streaming of activity events
  rpc StreamActivities(stream ActivityEvent) returns (stream ActivityAck);
  
  // Query historical activities
  rpc QueryActivities(ActivityQuery) returns (ActivityQueryResponse);
  
  // Get conversation turns
  rpc GetConversation(ConversationRequest) returns (ConversationResponse);
  
  // Stream real-time activities (server streaming)
  rpc SubscribeActivities(ActivitySubscription) returns (stream ActivityEvent);
}

message ActivityEvent {
  string event_id = 1;
  EventType type = 2;
  EventStatus status = 3;
  int64 duration_ms = 4;
  map<string, string> metadata = 5;
  ErrorDetails error = 6;
  string timestamp = 7;
  
  enum EventType {
    UNKNOWN = 0;
    CAPABILITY_INVOCATION = 1;
    CONVERSATION = 2;
    STATE_CHANGE = 3;
    ERROR = 4;
    METRICS_SNAPSHOT = 5;
  }
  
  enum EventStatus {
    PENDING = 0;
    SUCCESS = 1;
    ERROR = 2;
  }
}

message ErrorDetails {
  string message = 1;
  string stack = 2;
  int32 code = 3;
}

message ActivityAck {
  string event_id = 1;
  string status = 2;
  string message = 3;
}

message ActivityQuery {
  string agent_id = 1;
  repeated ActivityEvent.EventType types = 2;
  string from_timestamp = 3;
  string to_timestamp = 4;
  int32 limit = 5;
  int32 offset = 6;
  string search_query = 7;
}

message ActivityQueryResponse {
  repeated ActivityEvent events = 1;
  int32 total_count = 2;
  bool has_more = 3;
}

message ConversationRequest {
  string conversation_id = 1;
}

message ConversationResponse {
  string conversation_id = 1;
  repeated ConversationTurn turns = 2;
  ConversationMetadata metadata = 3;
}

message ConversationTurn {
  int32 turn_id = 1;
  int32 parent_turn_id = 2;
  string agent_id = 3;
  string message = 4;
  string response = 5;
  SemanticAnalysis analysis = 6;
  string timestamp = 7;
}

message ConversationMetadata {
  int32 total_turns = 1;
  string started_at = 2;
  string last_activity = 3;
  map<string, int32> sentiment_distribution = 4;
}

message ActivitySubscription {
  string agent_id = 1;
  repeated ActivityEvent.EventType types = 2;
  bool include_historical = 3;
}

3. OODA Coordination Proto

// proto/ooda_coordination.proto
syntax = "proto3";

package ossa.ooda;

option go_package = "github.com/ossa/agent-protocol/proto/ooda";

// OODA Coordination Service
service OODACoordinationService {
  // Coordinate OODA cycle across agents
  rpc CoordinateOODA(stream OODAPhase) returns (stream OODAPhase);
  
  // Execute OODA cycle (unary)
  rpc ExecuteCycle(OODACycleRequest) returns (OODACycleResponse);
  
  // Get current OODA state
  rpc GetState(GetStateRequest) returns (GetStateResponse);
  
  // Subscribe to OODA phase transitions
  rpc SubscribePhases(PhaseSubscription) returns (stream OODAPhase);
}

message OODAPhase {
  string agent_id = 1;
  string cycle_id = 2;
  Phase phase = 3;
  string data = 4;  // JSON-serialized phase data
  string timestamp = 5;
  map<string, string> metadata = 6;
  
  enum Phase {
    OBSERVE = 0;
    ORIENT = 1;
    DECIDE = 2;
    ACT = 3;
  }
}

message OODACycleRequest {
  string agent_id = 1;
  string trigger_data = 2;  // JSON-serialized
  map<string, string> context = 3;
}

message OODACycleResponse {
  string cycle_id = 1;
  repeated OODAPhase phases = 2;
  string result = 3;  // JSON-serialized action result
  int64 total_duration_ms = 4;
}

message GetStateRequest {
  string agent_id = 1;
  string cycle_id = 2;
}

message GetStateResponse {
  OODAState state = 1;
}

message OODAState {
  string agent_id = 1;
  string cycle_id = 2;
  OODAPhase.Phase current_phase = 3;
  repeated Observation observations = 4;
  Orientation orientation = 5;
  Decision decision = 6;
  Action action = 7;
  string started_at = 8;
  map<string, string> metadata = 9;
}

message Observation {
  string type = 1;
  string data = 2;  // JSON-serialized
  string source = 3;
  string timestamp = 4;
}

message Orientation {
  string analysis = 1;  // JSON-serialized analysis
  repeated string insights = 2;
  string severity = 3;
}

message Decision {
  string action_type = 1;
  repeated string targets = 2;
  string priority = 3;
  string reason = 4;
}

message Action {
  string action_type = 1;
  string result = 2;  // JSON-serialized
  bool success = 3;
  string error = 4;
}

message PhaseSubscription {
  string agent_id = 1;
  repeated OODAPhase.Phase phases = 2;
}

4. Mesh Observer Proto

// proto/mesh_observer.proto
syntax = "proto3";

package ossa.mesh;

option go_package = "github.com/ossa/agent-protocol/proto/mesh";

// Mesh Observer Service
service MeshObserverService {
  // Get current mesh graph
  rpc GetGraph(GetGraphRequest) returns (GetGraphResponse);
  
  // Stream mesh communications
  rpc WatchCommunications(WatchRequest) returns (stream CommunicationEvent);
  
  // Get agent relationships
  rpc GetRelationships(RelationshipsRequest) returns (RelationshipsResponse);
  
  // Export graph in various formats
  rpc ExportGraph(ExportRequest) returns (ExportResponse);
}

message GetGraphRequest {
  int64 time_window_seconds = 1;
}

message GetGraphResponse {
  AgentGraph graph = 1;
  string timestamp = 2;
}

message AgentGraph {
  repeated AgentNode nodes = 1;
  repeated AgentEdge edges = 2;
}

message AgentNode {
  string agent_id = 1;
  repeated string capabilities_called = 2;
  int32 call_count = 3;
  string last_seen = 4;
  map<string, string> metadata = 5;
}

message AgentEdge {
  string source = 1;
  string target = 2;
  int32 weight = 3;
  repeated string capabilities = 4;
  double avg_latency_ms = 5;
  int32 error_count = 6;
}

message WatchRequest {
  string agent_id = 1;
  bool include_errors_only = 2;
}

message CommunicationEvent {
  string source_agent_id = 1;
  string target_agent_id = 2;
  string capability = 3;
  int64 latency_ms = 4;
  bool success = 5;
  string timestamp = 6;
}

message RelationshipsRequest {
  string agent_id = 1;
  RelationshipDirection direction = 2;
  
  enum RelationshipDirection {
    BOTH = 0;
    OUTGOING = 1;
    INCOMING = 2;
  }
}

message RelationshipsResponse {
  repeated AgentRelationship relationships = 1;
}

message AgentRelationship {
  string related_agent_id = 1;
  string relationship_type = 2;
  int32 interaction_count = 3;
  double avg_latency_ms = 4;
}

message ExportRequest {
  ExportFormat format = 1;
  
  enum ExportFormat {
    JSON = 0;
    DOT = 1;
    GRAPHML = 2;
  }
}

message ExportResponse {
  string data = 1;
  string format = 2;
}

5. Semantic Analysis Proto

// proto/semantic_analysis.proto
syntax = "proto3";

package ossa.semantic;

option go_package = "github.com/ossa/agent-protocol/proto/semantic";

// Semantic Analysis Service
service SemanticAnalysisService {
  // Generate embeddings
  rpc GenerateEmbedding(EmbeddingRequest) returns (EmbeddingResponse);
  
  // Analyze text semantics
  rpc AnalyzeText(TextAnalysisRequest) returns (TextAnalysisResponse);
  
  // Calculate similarity
  rpc CalculateSimilarity(SimilarityRequest) returns (SimilarityResponse);
  
  // Find similar content
  rpc FindSimilar(FindSimilarRequest) returns (FindSimilarResponse);
}

message EmbeddingRequest {
  string text = 1;
  string model = 2;
}

message EmbeddingResponse {
  repeated float embedding = 1;
  int32 dimensions = 2;
}

message TextAnalysisRequest {
  string text = 1;
  bool include_sentiment = 2;
  bool include_intent = 3;
  bool include_entities = 4;
  bool include_topics = 5;
}

message TextAnalysisResponse {
  Sentiment sentiment = 1;
  Intent intent = 2;
  repeated Entity entities = 3;
  repeated string topics = 4;
}

message Sentiment {
  string value = 1;  // positive, negative, neutral
  double confidence = 2;
}

message Intent {
  string value = 1;
  double confidence = 2;
  repeated string keywords = 3;
}

message Entity {
  string type = 1;
  string value = 2;
  double confidence = 3;
  int32 start_position = 4;
  int32 end_position = 5;
}

message SimilarityRequest {
  repeated float embedding_a = 1;
  repeated float embedding_b = 2;
}

message SimilarityResponse {
  double similarity_score = 1;
}

message FindSimilarRequest {
  repeated float query_embedding = 1;
  int32 limit = 2;
  double similarity_threshold = 3;
  string conversation_id = 4;
}

message FindSimilarResponse {
  repeated SimilarItem items = 1;
}

message SimilarItem {
  string item_id = 1;
  double similarity_score = 2;
  map<string, string> metadata = 3;
}

Code Generation

# Generate TypeScript/JavaScript
protoc --plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts \
  --ts_out=src/proto \
  --js_out=import_style=commonjs,binary:src/proto \
  --grpc_out=grpc_js:src/proto \
  proto/*.proto

# Generate Go
protoc --go_out=. --go_opt=paths=source_relative \
  --go-grpc_out=. --go-grpc_opt=paths=source_relative \
  proto/*.proto

# Generate Python
python -m grpc_tools.protoc -I. \
  --python_out=. \
  --grpc_python_out=. \
  proto/*.proto

# Generate gRPC-Web for browser
protoc --plugin=protoc-gen-grpc-web=/usr/local/bin/protoc-gen-grpc-web \
  --grpc-web_out=import_style=typescript,mode=grpcwebtext:src/proto \
  proto/*.proto

Acceptance Criteria

• All 5 proto files created and documented
• Code generation scripts for TS, Go, Python, gRPC-Web
• Generated code compiles without errors
• Proto documentation with comments
• Example usage for each service
• Versioning strategy (e.g., ossa.agent.v1)
• Backwards compatibility guidelines
• Integration tests for all services

Files to Create

• proto/agent_communication.proto
• proto/activity_stream.proto
• proto/ooda_coordination.proto
• proto/mesh_observer.proto
• proto/semantic_analysis.proto
• scripts/generate-proto.sh
• docs/proto-reference.md

Related Issues

• OSSA #21: Activity streaming schema
• agent-brain #10: Activity stream service
• agent-mesh #6: Mesh observer
• agent-protocol #12: Protocol interceptors
• agent-protocol #13: MCP+OODA integration