@bluefly/openstandardagents 0.4.8 → 0.5.0

package/openapi/protocols/sse-streams.yaml

@@ -5,22 +5,18 @@ info:
   description: |
     OpenAPI extension for Server-Sent Events streams in OSSA.
     Defines SSE endpoints for unidirectional server-to-client event streaming.
-
   contact:
     name: OSSA Standards Team
     url: https://openstandardagents.org
-
 servers:
   - url: https://agent.example.com
     description: SSE server endpoint
-
 x-sse-config:
   heartbeat_interval_seconds: 30
   reconnect_time_ms: 3000
   max_event_buffer_size: 100
   event_retention_seconds: 300
   max_connections_per_client: 6
-
 paths:
   /events:
     get:
@@ -28,9 +24,7 @@ paths:
       description: |
         Subscribe to server-sent events from agent.
         Returns text/event-stream with continuous event delivery.
-
       operationId: subscribeToEvents
-
       parameters:
         - name: channels
           in: query
@@ -39,22 +33,21 @@ paths:
             type: string
           description: Comma-separated list of channels to subscribe to
           example: content.published,user.login,agent.status
-
         - name: last-event-id
           in: header
           required: false
           schema:
             type: string
           description: Resume from this event ID (for reconnection)
-
       responses:
-        '200':
+        "200":
           description: Event stream established
           headers:
             Content-Type:
               schema:
                 type: string
-                enum: [text/event-stream]
+                enum:
+                  - text/event-stream
             Cache-Control:
               schema:
                 type: string
@@ -62,66 +55,61 @@ paths:
             Connection:
               schema:
                 type: string
-                enum: [keep-alive]
+                enum:
+                  - keep-alive
             X-Accel-Buffering:
               schema:
                 type: string
-                enum: ['no']
+                enum:
+                  - no
               description: Disable buffering for real-time delivery
-
           content:
             text/event-stream:
               schema:
-                $ref: '#/components/schemas/EventStream'
-
+                $ref: "#/components/schemas/EventStream"
               examples:
                 message_event:
                   summary: Standard message event
                   value: |
                     event: message
                     id: msg-123e4567-e89b-12d3-a456-426614174000
-                    data: {"type":"message","timestamp":"2025-12-18T14:00:00Z","payload":{"channel":"content.published","data":{"contentId":"node-123"}},"metadata":{"agentId":"agent://example.com/publisher"}}
-
+                    data: {"type":"message","timestamp":"2025-12-18T14:00:00Z","payload":{"channel":"content.published","data":{"contentId":"node-123"}},"metadata":{"agentId":"uadp://example.com/publisher"}}
                 status_event:
                   summary: Status update event
                   value: |
                     event: status
                     id: status-456e7890-a12b-34c5-d678-901234567890
-                    data: {"type":"status","timestamp":"2025-12-18T14:00:00Z","payload":{"status":"healthy","load":0.45},"metadata":{"agentId":"agent://example.com/agent"}}
-
-        '401':
+                    data: {"type":"status","timestamp":"2025-12-18T14:00:00Z","payload":{"status":"healthy","load":0.45},"metadata":{"agentId":"uadp://example.com/agent"}}
+        "401":
           description: Unauthorized - Invalid authentication
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-
-        '429':
+                $ref: "#/components/schemas/Error"
+        "429":
           description: Too Many Requests - Connection limit exceeded
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-
+                $ref: "#/components/schemas/Error"
       security:
         - bearerAuth: []
         - cookieAuth: []
         - queryToken: []
-
       x-sse-events:
-        - $ref: '#/components/x-sse-events/Message'
-        - $ref: '#/components/x-sse-events/Status'
-        - $ref: '#/components/x-sse-events/CapabilityResponse'
-        - $ref: '#/components/x-sse-events/Error'
-
+        - $ref: "#/components/x-sse-events/Message"
+        - $ref: "#/components/x-sse-events/Status"
+        - $ref: "#/components/x-sse-events/CapabilityResponse"
+        - $ref: "#/components/x-sse-events/Error"
+      x-ossa-capability: protocol-subscribe-to-events
+      tags:
+        - SSE
   /events/stream/{streamId}:
     get:
       summary: Dedicated stream endpoint
       description: |
         Subscribe to a specific event stream (e.g., for a long-running capability execution).
-
       operationId: subscribeToStream
-
       parameters:
         - name: streamId
           in: path
@@ -130,34 +118,31 @@ paths:
             type: string
             format: uuid
           description: Stream identifier from initiating request
-
       responses:
-        '200':
+        "200":
           description: Stream established
           content:
             text/event-stream:
               schema:
-                $ref: '#/components/schemas/EventStream'
-
-        '404':
+                $ref: "#/components/schemas/EventStream"
+        "404":
           description: Stream not found
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-
+                $ref: "#/components/schemas/Error"
       security:
         - bearerAuth: []
-
+      x-ossa-capability: protocol-subscribe-to-stream
+      tags:
+        - SSE
   /capabilities/{capability}/invoke:
     post:
       summary: Invoke capability with streaming response
       description: |
         Invoke a capability that returns streaming results via SSE.
         Response includes streamId to connect to SSE endpoint.
-
       operationId: invokeCapabilityStreaming
-
       parameters:
         - name: capability
           in: path
@@ -166,7 +151,6 @@ paths:
             type: string
           description: Capability name to invoke
           example: analyze_content
-
       requestBody:
         required: true
         content:
@@ -185,10 +169,13 @@ paths:
                       minimum: 1
                     priority:
                       type: string
-                      enum: [low, normal, high, critical]
-
+                      enum:
+                        - low
+                        - normal
+                        - high
+                        - critical
       responses:
-        '202':
+        "202":
           description: Capability invocation accepted, streaming in progress
           content:
             application/json:
@@ -205,17 +192,20 @@ paths:
                     type: string
                     format: uri
                     example: https://agent.example.com/events/stream/abc-123
-
-        '400':
+        "400":
           description: Invalid request
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-
+                $ref: "#/components/schemas/Error"
       security:
         - bearerAuth: []
-
+      x-ossa-capability: protocol-invoke-capability-streaming
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      tags:
+        - SSE
 components:
   x-sse-events:
     Message:
@@ -224,8 +214,7 @@ components:
       event:
         name: message
         schema:
-          $ref: '#/components/schemas/SSEEvent'
-
+          $ref: "#/components/schemas/SSEEvent"
     Status:
       summary: Agent status update
       description: Periodic health and status broadcasts
@@ -233,7 +222,7 @@ components:
         name: status
         schema:
           allOf:
-            - $ref: '#/components/schemas/SSEEvent'
+            - $ref: "#/components/schemas/SSEEvent"
             - type: object
               required:
                 - payload
@@ -245,7 +234,11 @@ components:
                   properties:
                     status:
                       type: string
-                      enum: [healthy, degraded, unhealthy, offline]
+                      enum:
+                        - healthy
+                        - degraded
+                        - unhealthy
+                        - offline
                     load:
                       type: number
                       minimum: 0
@@ -257,7 +250,6 @@ components:
                     metrics:
                       type: object
                       additionalProperties: true
-
     CapabilityResponse:
       summary: Streaming capability response
       description: Response chunks from capability execution
@@ -265,7 +257,7 @@ components:
         name: capability_response
         schema:
           allOf:
-            - $ref: '#/components/schemas/SSEEvent'
+            - $ref: "#/components/schemas/SSEEvent"
             - type: object
               required:
                 - payload
@@ -295,14 +287,13 @@ components:
                           type: integer
                 metadata:
                   allOf:
-                    - $ref: '#/components/schemas/EventMetadata'
+                    - $ref: "#/components/schemas/EventMetadata"
                     - type: object
                       properties:
                         final:
                           type: boolean
                           description: True if this is the last event
                           default: false
-
     Error:
       summary: Error event
       description: Error notification
@@ -310,7 +301,7 @@ components:
         name: error
         schema:
           allOf:
-            - $ref: '#/components/schemas/SSEEvent'
+            - $ref: "#/components/schemas/SSEEvent"
             - type: object
               required:
                 - payload
@@ -333,7 +324,6 @@ components:
                     retryable:
                       type: boolean
                       default: false
-
   schemas:
     EventStream:
       type: string
@@ -347,7 +337,6 @@ components:
         retry: <reconnect-time-ms>
         data: <json-payload>
         (blank line)
-
       example: |
         event: message
         id: msg-123
@@ -359,8 +348,6 @@ components:
         event: status
         id: status-456
         data: {"type":"status","payload":{...}}
-
-
     SSEEvent:
       type: object
       required:
@@ -390,8 +377,7 @@ components:
           type: object
           description: Event-specific payload
         metadata:
-          $ref: '#/components/schemas/EventMetadata'
-
+          $ref: "#/components/schemas/EventMetadata"
     EventMetadata:
       type: object
       required:
@@ -401,7 +387,7 @@ components:
           type: string
           format: uri
           description: Agent URI of sender
-          example: agent://example.com/supercali-fragilisticagent
+          example: uadp://example.com/supercali-fragilisticagent
         streamId:
           type: string
           format: uuid
@@ -418,7 +404,6 @@ components:
           type: boolean
           description: Indicates last event in sequence
           default: false
-
     Error:
       type: object
       required:
@@ -432,44 +417,36 @@ components:
         details:
           type: object
           additionalProperties: true
-
   securitySchemes:
     bearerAuth:
       type: http
       scheme: bearer
       bearerFormat: JWT
-
     cookieAuth:
       type: apiKey
       in: cookie
       name: session
-
     queryToken:
       type: apiKey
       in: query
       name: token
-
 security:
   - bearerAuth: []
   - cookieAuth: []
-
 x-rate-limits:
   events_per_second: 50
   max_connections_per_client: 6
   max_event_size_bytes: 65536
-
 x-reliability:
   event_buffer_size: 100
   event_retention_seconds: 300
   heartbeat_interval_seconds: 30
   auto_reconnect: true
   reconnect_time_ms: 3000
-
 x-cors:
   allowed_origins:
     - https://trusted-domain.com
   allow_credentials: true
-
 tags:
   - name: Events
     description: Event stream subscriptions
@@ -477,3 +454,18 @@ tags:
     description: Streaming capability invocations
   - name: Health
     description: Agent health monitoring
+  - name: SSE
+    description: SSE operations
+x-ossa-metadata:
+  version: 0.3.3
+  compliance:
+    level: standard
+  observability:
+    tracing: true
+    metrics: true
+    logging: true
+x-ossa:
+  version: 0.5.0
+  agent:
+    id: protocols-sse-streams
+    type: integrator