syntax = "proto3";

package clawx;

// Core frame message — all communication uses this envelope
message AgentFrame {
  string id = 1;
  string type = 2;          // register, registered, heartbeat, task_started, etc.
  int64  timestamp = 3;

  // Routing
  string from_agent_id = 4;
  string to_agent_id = 5;   // "broadcast" for broadcast, "server" for master

  // Operation scoping
  string parent_operation_id = 6;
  string parent_operation_type = 7;  // "chat" or "task"

  // Payload as JSON bytes (flexible schema per frame type)
  bytes  payload = 8;

  // Error string (set on error frames)
  string error = 9;
}

// Health checking
message HealthCheckRequest {
  string service = 1;
}

message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
  }
  ServingStatus status = 1;
  string agent_id = 2;
  string agent_name = 3;
  int32  connected_agents = 4;
}

// Registration
message RegisterRequest {
  string agent_id = 1;
  string agent_name = 2;
  string endpoint = 3;
  repeated string capabilities = 4;
  bytes  persona = 5;       // JSON-encoded Persona
}

message RegisterResponse {
  string agent_id = 1;
  string status = 2;        // "registered" or "rejected"
  string message = 3;
  string master_endpoint = 4;
}

// Heartbeat
message HeartbeatRequest {
  string agent_id = 1;
  int64  timestamp = 2;
}

message HeartbeatResponse {
  bool   ok = 1;
  int64  server_time = 2;
}

// Task execution
message TaskRequest {
  string task_id = 1;
  string tool = 2;
  bytes  params = 3;        // JSON-encoded tool params
  bytes  context = 4;       // JSON-encoded execution context
}

message TaskEvent {
  string task_id = 1;
  string type = 2;          // task_started, tool_stdout, task_completed, etc.
  bytes  payload = 3;       // JSON-encoded event payload
  string error = 4;
}

// Task cancellation
message CancelTaskRequest {
  string task_id = 1;
  string reason = 2;
}

message CancelTaskResponse {
  bool   ok = 1;
  string message = 2;
}

// Chat
message ChatRequest {
  string conversation_id = 1;
  string message = 2;
  bytes  context = 3;       // JSON-encoded chat context
}

message ChatEvent {
  string conversation_id = 1;
  string type = 2;          // agent_message_start, agent_message_delta, agent_message_end
  bytes  payload = 3;       // JSON-encoded event payload
}

// === Services ===

// The main agent service — bidirectional stream for backwards compat,
// plus separate RPCs for structured operations
service ClawxAgentService {
  // Legacy bidirectional stream (kept for backwards compat)
  rpc Connect (stream AgentFrame) returns (stream AgentFrame);

  // Structured RPCs
  rpc Register (RegisterRequest) returns (RegisterResponse);
  rpc Heartbeat (HeartbeatRequest) returns (HeartbeatResponse);
  rpc ExecuteTask (TaskRequest) returns (stream TaskEvent);
  rpc CancelTask (CancelTaskRequest) returns (CancelTaskResponse);
  rpc SendChat (ChatRequest) returns (stream ChatEvent);
}

// Standard gRPC health checking
service Health {
  rpc Check (HealthCheckRequest) returns (HealthCheckResponse);
}
