@bluefly/openstandardagents 0.2.9 → 0.3.0

package/openapi/protocols/websocket-events.yaml

@@ -0,0 +1,427 @@
+openapi: 3.1.0
+info:
+  title: OSSA WebSocket Events API
+  version: 0.3.0
+  description: |
+    OpenAPI extension for WebSocket event definitions in OSSA.
+    Defines event schemas for bidirectional agent-to-agent messaging over WebSocket.
+
+  contact:
+    name: OSSA Standards Team
+    url: https://openstandardagents.org
+
+servers:
+  - url: wss://agent.example.com
+    description: WebSocket server endpoint
+
+x-websocket-config:
+  protocol: ossa.v0.3.0
+  keepalive:
+    ping_interval_seconds: 30
+    pong_timeout_seconds: 5
+    max_missed_pongs: 3
+  compression:
+    enabled: true
+    method: permessage-deflate
+  max_message_size_bytes: 1048576  # 1MB
+  max_connections_per_agent: 10
+
+paths:
+  /ws:
+    get:
+      summary: WebSocket connection endpoint
+      description: |
+        Establish WebSocket connection for agent-to-agent messaging.
+        Client must send registration event after connection.
+
+      parameters:
+        - name: Authorization
+          in: header
+          required: false
+          schema:
+            type: string
+          description: Bearer token for authentication (preferred)
+
+        - name: token
+          in: query
+          required: false
+          schema:
+            type: string
+          description: JWT token for authentication (fallback for restricted environments)
+
+      responses:
+        '101':
+          description: Switching Protocols - WebSocket connection established
+          headers:
+            Upgrade:
+              schema:
+                type: string
+                enum: [websocket]
+            Connection:
+              schema:
+                type: string
+                enum: [Upgrade]
+            Sec-WebSocket-Accept:
+              schema:
+                type: string
+
+        '401':
+          description: Unauthorized - Invalid or missing authentication
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+        '429':
+          description: Too Many Requests - Connection limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+      x-websocket-events:
+        - $ref: '#/components/websocket-events/Register'
+        - $ref: '#/components/websocket-events/Message'
+        - $ref: '#/components/websocket-events/CapabilityCall'
+        - $ref: '#/components/websocket-events/StatusUpdate'
+        - $ref: '#/components/websocket-events/Error'
+        - $ref: '#/components/websocket-events/Acknowledgment'
+        - $ref: '#/components/websocket-events/Ping'
+        - $ref: '#/components/websocket-events/Pong'
+
+components:
+  websocket-events:
+    Register:
+      summary: Agent registration event
+      description: Sent by client immediately after connection to register agent identity
+      direction: client-to-server
+      event:
+        type: register
+        schema:
+          type: object
+          required:
+            - type
+            - agentId
+            - capabilities
+            - version
+          properties:
+            type:
+              type: string
+              const: register
+            agentId:
+              type: string
+              format: uri
+              description: Agent URI (agent://domain/agent-id)
+              example: agent://example.com/my-agent
+            capabilities:
+              type: array
+              items:
+                type: string
+              description: List of capabilities this agent provides
+              example: [process_data, analyze_content]
+            version:
+              type: string
+              description: OSSA protocol version
+              example: ossa/v0.3.0
+
+    Message:
+      summary: General message event
+      description: Pub/sub style message broadcast
+      direction: bidirectional
+      event:
+        type: message
+        schema:
+          $ref: '#/components/schemas/WebSocketEvent'
+
+    CapabilityCall:
+      summary: Capability invocation event
+      description: RPC-style capability call with request/response pattern
+      direction: bidirectional
+      event:
+        type: capability_call
+        schema:
+          allOf:
+            - $ref: '#/components/schemas/WebSocketEvent'
+            - type: object
+              required:
+                - payload
+              properties:
+                payload:
+                  type: object
+                  required:
+                    - capability
+                    - input
+                  properties:
+                    capability:
+                      type: string
+                      description: Name of capability to invoke
+                    input:
+                      type: object
+                      description: Capability input parameters
+                metadata:
+                  allOf:
+                    - $ref: '#/components/schemas/EventMetadata'
+                    - type: object
+                      required:
+                        - correlationId
+                        - replyTo
+                      properties:
+                        correlationId:
+                          type: string
+                          format: uuid
+                        replyTo:
+                          type: string
+                          description: WebSocket connection ID for response
+
+    StatusUpdate:
+      summary: Agent status update event
+      description: Periodic health and status broadcasts
+      direction: bidirectional
+      event:
+        type: status_update
+        schema:
+          allOf:
+            - $ref: '#/components/schemas/WebSocketEvent'
+            - type: object
+              required:
+                - payload
+              properties:
+                payload:
+                  type: object
+                  required:
+                    - status
+                  properties:
+                    status:
+                      type: string
+                      enum: [healthy, degraded, unhealthy, offline]
+                    load:
+                      type: number
+                      minimum: 0
+                      maximum: 1
+                      description: Current load (0.0 - 1.0)
+                    activeConnections:
+                      type: integer
+                      minimum: 0
+                    capabilities:
+                      type: array
+                      items:
+                        type: string
+                    metrics:
+                      type: object
+                      additionalProperties: true
+
+    Error:
+      summary: Error event
+      description: Error notification for failed operations
+      direction: bidirectional
+      event:
+        type: error
+        schema:
+          allOf:
+            - $ref: '#/components/schemas/WebSocketEvent'
+            - type: object
+              required:
+                - payload
+              properties:
+                payload:
+                  type: object
+                  required:
+                    - code
+                    - message
+                  properties:
+                    code:
+                      type: string
+                      enum:
+                        - AUTH_FAILED
+                        - CAPABILITY_NOT_FOUND
+                        - RATE_LIMIT_EXCEEDED
+                        - PAYLOAD_TOO_LARGE
+                        - PROTOCOL_ERROR
+                        - INTERNAL_ERROR
+                    message:
+                      type: string
+                    details:
+                      type: object
+                      additionalProperties: true
+                    retryable:
+                      type: boolean
+                      default: false
+
+    Acknowledgment:
+      summary: Message acknowledgment
+      description: Confirms message receipt for at-least-once delivery
+      direction: bidirectional
+      event:
+        type: ack
+        schema:
+          allOf:
+            - $ref: '#/components/schemas/WebSocketEvent'
+            - type: object
+              required:
+                - payload
+              properties:
+                payload:
+                  type: object
+                  required:
+                    - messageId
+                    - status
+                  properties:
+                    messageId:
+                      type: string
+                      format: uuid
+                    status:
+                      type: string
+                      enum: [received, processed, failed]
+
+    Ping:
+      summary: Keepalive ping
+      description: Server-initiated heartbeat to maintain connection
+      direction: server-to-client
+      event:
+        type: ping
+        schema:
+          type: object
+          required:
+            - type
+            - timestamp
+          properties:
+            type:
+              type: string
+              const: ping
+            timestamp:
+              type: string
+              format: date-time
+
+    Pong:
+      summary: Keepalive pong
+      description: Client response to ping
+      direction: client-to-server
+      event:
+        type: pong
+        schema:
+          type: object
+          required:
+            - type
+            - timestamp
+          properties:
+            type:
+              type: string
+              const: pong
+            timestamp:
+              type: string
+              format: date-time
+
+  schemas:
+    WebSocketEvent:
+      type: object
+      required:
+        - type
+        - id
+        - timestamp
+        - payload
+        - metadata
+      properties:
+        type:
+          type: string
+          enum:
+            - message
+            - capability_call
+            - status_update
+            - error
+            - ack
+          description: Event type discriminator
+        id:
+          type: string
+          format: uuid
+          description: Unique event identifier
+        timestamp:
+          type: string
+          format: date-time
+          description: Event timestamp (ISO 8601)
+        payload:
+          type: object
+          description: Event-specific payload
+        metadata:
+          $ref: '#/components/schemas/EventMetadata'
+
+    EventMetadata:
+      type: object
+      required:
+        - agentId
+      properties:
+        agentId:
+          type: string
+          format: uri
+          description: Agent URI of sender
+          example: agent://example.com/my-agent
+        correlationId:
+          type: string
+          format: uuid
+          description: For request/response correlation
+        replyTo:
+          type: string
+          description: Connection ID or endpoint for responses
+        priority:
+          type: string
+          enum: [low, normal, high, critical]
+          default: normal
+        ttl:
+          type: integer
+          minimum: 1
+          description: Time-to-live in seconds
+        retryCount:
+          type: integer
+          minimum: 0
+          description: Number of retry attempts
+
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+        message:
+          type: string
+        details:
+          type: object
+          additionalProperties: true
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+    queryToken:
+      type: apiKey
+      in: query
+      name: token
+
+security:
+  - bearerAuth: []
+  - queryToken: []
+
+x-rate-limits:
+  messages_per_second: 100
+  max_payload_size_bytes: 1048576
+  burst_size: 200
+
+x-reliability:
+  delivery_guarantee: at-least-once
+  retry_policy:
+    max_attempts: 3
+    backoff: exponential
+    initial_delay_ms: 1000
+    max_delay_ms: 30000
+
+tags:
+  - name: Connection
+    description: WebSocket connection management
+  - name: Messaging
+    description: Agent-to-agent messaging
+  - name: Capabilities
+    description: Capability invocation
+  - name: Health
+    description: Agent health and status