@bluefly/openstandardagents 0.2.9 → 0.3.0

package/openapi/agent-discovery.yaml

@@ -0,0 +1,677 @@
+openapi: 3.1.0
+info:
+  title: OSSA Agent Discovery & Registry API
+  version: 1.0.0
+  description: |
+    Agent Discovery and Registry API for OSSA v0.3.0.
+
+    This API enables:
+    - Dynamic agent registration and unregistration
+    - Agent discovery by domain, subdomain, and concerns
+    - Capability-based agent matching
+    - Registry health monitoring
+
+    **Discovery Taxonomy:**
+    - `domain::*` - Primary functional domain (e.g., domain::security, domain::documentation)
+    - `subdomain::*` - Specialized area within domain (e.g., subdomain::scanning, subdomain::compliance)
+    - `concern::*` - Cross-cutting concerns (e.g., concern::quality, concern::performance)
+    - `capability` - Specific capabilities agents provide
+
+    **OpenAPI-First Architecture:**
+    - Drives type generation for SDK clients
+    - Validates requests and responses
+    - Self-documenting API
+  contact:
+    name: OSSA Registry Team
+    url: https://registry.openstandardagents.org
+    email: registry@openstandardagents.org
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+
+servers:
+  - url: https://registry.openstandardagents.org/api/v1
+    description: Production Registry
+  - url: https://staging.registry.openstandardagents.org/api/v1
+    description: Staging Registry
+  - url: http://localhost:3100/api/v1
+    description: Local Development
+
+tags:
+  - name: registry
+    description: Agent registration and lifecycle
+  - name: discovery
+    description: Agent discovery and search
+  - name: health
+    description: Registry health and status
+
+paths:
+  /registry/register:
+    post:
+      summary: Register agent with the registry
+      description: |
+        Register a new agent or update an existing agent's metadata in the registry.
+        Agents self-register on startup and update their status periodically.
+      operationId: registerAgent
+      tags: [registry]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegistrationRequest'
+            examples:
+              securityAgent:
+                summary: Security scanning agent
+                value:
+                  agentId: security-scanner-01
+                  name: security-scanner
+                  version: 1.0.0
+                  manifest:
+                    apiVersion: ossa/v0.3.0
+                    kind: Agent
+                    metadata:
+                      name: security-scanner
+                      version: 1.0.0
+                      description: Automated security vulnerability scanner
+                      labels:
+                        domain: security
+                        subdomain: scanning
+                        capability: vulnerability-detection
+                        team: security-ops
+                  endpoint: https://agents.example.com/security-scanner
+                  domains:
+                    - domain::security
+                  subdomains:
+                    - subdomain::scanning
+                    - subdomain::compliance
+                  concerns:
+                    - concern::quality
+                    - concern::security
+                  capabilities:
+                    - vulnerability-detection
+                    - dependency-audit
+                    - security-reporting
+                  status: active
+                  healthEndpoint: https://agents.example.com/security-scanner/health
+      responses:
+        '201':
+          description: Agent successfully registered
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - agentId
+                  - status
+                  - registeredAt
+                properties:
+                  agentId:
+                    type: string
+                    description: Unique agent identifier
+                  status:
+                    type: string
+                    enum: [registered, updated]
+                  registeredAt:
+                    type: string
+                    format: date-time
+                  expiresAt:
+                    type: string
+                    format: date-time
+                    description: Registration expiry (requires renewal)
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          description: Agent ID conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /registry/unregister/{agentId}:
+    delete:
+      summary: Unregister agent from registry
+      description: |
+        Remove an agent from the registry. Agents should unregister on graceful shutdown.
+        The registry will also automatically expire agents that fail health checks.
+      operationId: unregisterAgent
+      tags: [registry]
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: agentId
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+          description: Unique agent identifier
+      responses:
+        '204':
+          description: Agent successfully unregistered
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /registry/discover:
+    get:
+      summary: Discover agents by criteria
+      description: |
+        Search for agents matching specific discovery criteria.
+        Supports filtering by domain, subdomain, concerns, and capabilities.
+
+        **Query Patterns:**
+        - Domain only: `?domain=domain::security`
+        - Domain + subdomain: `?domain=domain::security&subdomain=subdomain::scanning`
+        - Multiple concerns: `?concerns=concern::quality,concern::performance`
+        - Capabilities: `?capabilities=vulnerability-detection,dependency-audit`
+        - Combined: All parameters can be combined for precise matching
+      operationId: discoverAgents
+      tags: [discovery]
+      parameters:
+        - name: domain
+          in: query
+          schema:
+            type: string
+            pattern: '^domain::[a-z0-9-]+$'
+          description: Primary functional domain (e.g., domain::security)
+          example: domain::security
+        - name: subdomain
+          in: query
+          schema:
+            type: string
+            pattern: '^subdomain::[a-z0-9-]+$'
+          description: Specialized area within domain (e.g., subdomain::scanning)
+          example: subdomain::scanning
+        - name: concerns
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+              pattern: '^concern::[a-z0-9-]+$'
+          style: form
+          explode: false
+          description: Cross-cutting concerns (comma-separated)
+          example: concern::quality,concern::security
+        - name: capabilities
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+              pattern: '^[a-z][a-z0-9_-]*$'
+          style: form
+          explode: false
+          description: Required capabilities (comma-separated)
+          example: vulnerability-detection,security-reporting
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, inactive, degraded, maintenance]
+          description: Filter by agent status
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+          description: Maximum number of results
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+          description: Pagination offset
+      responses:
+        '200':
+          description: Matching agents found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DiscoveryResult'
+              examples:
+                securityAgents:
+                  summary: Security domain agents
+                  value:
+                    total: 2
+                    limit: 20
+                    offset: 0
+                    agents:
+                      - agentId: security-scanner-01
+                        name: security-scanner
+                        version: 1.0.0
+                        domains:
+                          - domain::security
+                        subdomains:
+                          - subdomain::scanning
+                        concerns:
+                          - concern::quality
+                        capabilities:
+                          - vulnerability-detection
+                          - dependency-audit
+                        status: active
+                        endpoint: https://agents.example.com/security-scanner
+                        lastSeen: '2025-12-18T14:00:00Z'
+                        registeredAt: '2025-12-18T10:00:00Z'
+                      - agentId: compliance-auditor-01
+                        name: compliance-auditor
+                        version: 1.0.0
+                        domains:
+                          - domain::security
+                        subdomains:
+                          - subdomain::compliance
+                        concerns:
+                          - concern::quality
+                          - concern::governance
+                        capabilities:
+                          - compliance-audit
+                          - report-generation
+                        status: active
+                        endpoint: https://agents.example.com/compliance-auditor
+                        lastSeen: '2025-12-18T13:55:00Z'
+                        registeredAt: '2025-12-18T10:00:00Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /registry/health:
+    get:
+      summary: Registry health check
+      description: |
+        Get the health status of the registry service.
+        Returns current registry statistics and operational status.
+      operationId: getRegistryHealth
+      tags: [health]
+      responses:
+        '200':
+          description: Registry is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - status
+                  - timestamp
+                  - version
+                properties:
+                  status:
+                    type: string
+                    enum: [healthy, degraded, unhealthy]
+                  timestamp:
+                    type: string
+                    format: date-time
+                  version:
+                    type: string
+                    description: Registry API version
+                  uptime:
+                    type: integer
+                    description: Uptime in seconds
+                  statistics:
+                    type: object
+                    properties:
+                      totalAgents:
+                        type: integer
+                      activeAgents:
+                        type: integer
+                      inactiveAgents:
+                        type: integer
+                      degradedAgents:
+                        type: integer
+                      totalDomains:
+                        type: integer
+                      totalCapabilities:
+                        type: integer
+              example:
+                status: healthy
+                timestamp: '2025-12-18T14:00:00Z'
+                version: 1.0.0
+                uptime: 86400
+                statistics:
+                  totalAgents: 42
+                  activeAgents: 38
+                  inactiveAgents: 2
+                  degradedAgents: 2
+                  totalDomains: 8
+                  totalCapabilities: 125
+        '503':
+          description: Registry is unavailable
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [unhealthy]
+                  message:
+                    type: string
+                  timestamp:
+                    type: string
+                    format: date-time
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token for agent authentication
+
+  schemas:
+    RegistrationRequest:
+      type: object
+      required:
+        - agentId
+        - name
+        - version
+        - manifest
+        - endpoint
+        - status
+      properties:
+        agentId:
+          type: string
+          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+          maxLength: 253
+          description: Unique agent identifier (DNS-1123 subdomain format)
+          example: security-scanner-01
+        name:
+          type: string
+          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+          maxLength: 253
+          description: Agent name (from manifest.metadata.name)
+          example: security-scanner
+        version:
+          type: string
+          pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
+          description: Semantic version (semver 2.0.0)
+          example: 1.0.0
+        manifest:
+          type: object
+          description: Complete OSSA v0.3.0 manifest
+          required:
+            - apiVersion
+            - kind
+            - metadata
+          properties:
+            apiVersion:
+              type: string
+              pattern: '^ossa/v0\.3\.[0-9]+$'
+            kind:
+              type: string
+              enum: [Agent, Task, Workflow]
+            metadata:
+              type: object
+              required: [name, version]
+              properties:
+                name:
+                  type: string
+                version:
+                  type: string
+                description:
+                  type: string
+                labels:
+                  type: object
+                  additionalProperties:
+                    type: string
+        endpoint:
+          type: string
+          format: uri
+          description: Agent API endpoint
+          example: https://agents.example.com/security-scanner
+        domains:
+          type: array
+          items:
+            type: string
+            pattern: '^domain::[a-z0-9-]+$'
+          description: Primary functional domains
+          example:
+            - domain::security
+        subdomains:
+          type: array
+          items:
+            type: string
+            pattern: '^subdomain::[a-z0-9-]+$'
+          description: Specialized subdomains
+          example:
+            - subdomain::scanning
+            - subdomain::compliance
+        concerns:
+          type: array
+          items:
+            type: string
+            pattern: '^concern::[a-z0-9-]+$'
+          description: Cross-cutting concerns
+          example:
+            - concern::quality
+            - concern::security
+        capabilities:
+          type: array
+          items:
+            type: string
+            pattern: '^[a-z][a-z0-9_-]*$'
+          description: Capabilities provided by agent
+          example:
+            - vulnerability-detection
+            - dependency-audit
+        status:
+          type: string
+          enum: [active, inactive, degraded, maintenance]
+          description: Current agent status
+        healthEndpoint:
+          type: string
+          format: uri
+          description: Health check endpoint
+          example: https://agents.example.com/security-scanner/health
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Additional agent metadata
+
+    AgentMetadata:
+      type: object
+      required:
+        - agentId
+        - name
+        - version
+        - status
+        - endpoint
+        - registeredAt
+        - lastSeen
+      properties:
+        agentId:
+          type: string
+          description: Unique agent identifier
+        name:
+          type: string
+          description: Agent name
+        version:
+          type: string
+          description: Agent version
+        domains:
+          type: array
+          items:
+            type: string
+          description: Primary functional domains
+        subdomains:
+          type: array
+          items:
+            type: string
+          description: Specialized subdomains
+        concerns:
+          type: array
+          items:
+            type: string
+          description: Cross-cutting concerns
+        capabilities:
+          type: array
+          items:
+            type: string
+          description: Agent capabilities
+        status:
+          type: string
+          enum: [active, inactive, degraded, maintenance]
+        endpoint:
+          type: string
+          format: uri
+          description: Agent API endpoint
+        healthEndpoint:
+          type: string
+          format: uri
+          description: Health check endpoint
+        registeredAt:
+          type: string
+          format: date-time
+          description: Registration timestamp
+        lastSeen:
+          type: string
+          format: date-time
+          description: Last heartbeat timestamp
+        expiresAt:
+          type: string
+          format: date-time
+          description: Registration expiry (requires renewal)
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Additional metadata
+
+    DiscoveryQuery:
+      type: object
+      properties:
+        domain:
+          type: string
+          pattern: '^domain::[a-z0-9-]+$'
+          description: Primary functional domain filter
+        subdomain:
+          type: string
+          pattern: '^subdomain::[a-z0-9-]+$'
+          description: Subdomain filter
+        concerns:
+          type: array
+          items:
+            type: string
+            pattern: '^concern::[a-z0-9-]+$'
+          description: Concerns filter (match any)
+        capabilities:
+          type: array
+          items:
+            type: string
+            pattern: '^[a-z][a-z0-9_-]*$'
+          description: Capabilities filter (match all)
+        status:
+          type: string
+          enum: [active, inactive, degraded, maintenance]
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+        offset:
+          type: integer
+          minimum: 0
+          default: 0
+
+    DiscoveryResult:
+      type: object
+      required:
+        - total
+        - limit
+        - offset
+        - agents
+      properties:
+        total:
+          type: integer
+          description: Total matching agents
+        limit:
+          type: integer
+          description: Result limit
+        offset:
+          type: integer
+          description: Result offset
+        agents:
+          type: array
+          items:
+            $ref: '#/components/schemas/AgentMetadata'
+
+    Error:
+      type: object
+      required:
+        - error
+        - message
+      properties:
+        error:
+          type: string
+          description: Error code
+        message:
+          type: string
+          description: Human-readable error message
+        details:
+          type: object
+          additionalProperties: true
+          description: Additional error details
+        trace_id:
+          type: string
+          format: uuid
+          description: Request trace ID for debugging
+
+  responses:
+    BadRequest:
+      description: Bad request - invalid input
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: bad_request
+            message: Invalid discovery query parameters
+            details:
+              field: domain
+              issue: Must match pattern 'domain::[a-z0-9-]+'
+            trace_id: 550e8400-e29b-41d4-a716-446655440000
+
+    Unauthorized:
+      description: Unauthorized - missing or invalid authentication
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: unauthorized
+            message: Missing or invalid authentication token
+            trace_id: 550e8400-e29b-41d4-a716-446655440000
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: not_found
+            message: Agent not found
+            trace_id: 550e8400-e29b-41d4-a716-446655440000
+
+    InternalError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: internal_error
+            message: An unexpected error occurred
+            trace_id: 550e8400-e29b-41d4-a716-446655440000