@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/docs/agent-openapi-spec.yml

@@ -1,942 +0,0 @@
-openapi: 3.1.0
-info:
-  title: OSSA Agent API Specification
-  version: '@bluefly/ossa/v0.1.9'
-  description: |
-    Complete OpenAPI 3.1 specification for an OSSA-compliant agent.
-    This specification defines the complete interface that every OSSA agent must implement,
-    including health checks, capability discovery, execution endpoints, and lifecycle management.
-
-    **Agent Types Supported:**
-    - orchestrator: Coordinates multiple agents and workflows
-    - worker: Performs specific tasks and operations
-    - critic: Reviews and validates agent outputs
-    - judge: Makes decisions and evaluates outcomes
-    - trainer: Handles agent learning and improvement
-    - governor: Enforces policies and compliance
-    - monitor: Observes and reports on system state
-    - integrator: Connects systems and protocols
-    - voice: Handles audio/speech interactions
-
-  contact:
-    name: OSSA Specification Team
-    url: https://github.com/bluefly-io/ossa
-  license:
-    name: MIT
-    url: https://opensource.org/licenses/MIT
-
-servers:
-  - url: http://localhost:3000
-    description: Local development server
-  - url: https://agent.{environment}.{domain}
-    description: Production agent endpoint
-    variables:
-      environment:
-        default: prod
-        enum: [dev, staging, prod]
-      domain:
-        default: ossa.io
-
-tags:
-  - name: Health
-    description: Agent health and status monitoring
-  - name: Capabilities
-    description: Agent capability discovery and configuration
-  - name: Execution
-    description: Agent task execution and processing
-  - name: Lifecycle
-    description: Agent lifecycle management
-  - name: Communication
-    description: Inter-agent communication
-  - name: Model Context Protocol
-    description: MCP integration for model interactions
-
-paths:
-  /health:
-    get:
-      tags: [Health]
-      summary: Basic health check
-      description: Returns the basic health status of the agent
-      operationId: getHealth
-      responses:
-        '200':
-          description: Agent is healthy
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/HealthStatus'
-        '503':
-          description: Agent is unhealthy
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /health/live:
-    get:
-      tags: [Health]
-      summary: Liveness probe
-      description: Kubernetes-style liveness probe for the agent
-      operationId: getLiveness
-      responses:
-        '200':
-          description: Agent is alive
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/LivenessStatus'
-        '503':
-          description: Agent is not responding
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /health/ready:
-    get:
-      tags: [Health]
-      summary: Readiness probe
-      description: Kubernetes-style readiness probe for the agent
-      operationId: getReadiness
-      responses:
-        '200':
-          description: Agent is ready to accept requests
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ReadinessStatus'
-        '503':
-          description: Agent is not ready
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /health/startup:
-    get:
-      tags: [Health]
-      summary: Startup probe
-      description: Kubernetes-style startup probe for the agent
-      operationId: getStartup
-      responses:
-        '200':
-          description: Agent has started successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/StartupStatus'
-        '503':
-          description: Agent is still starting
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /capabilities:
-    get:
-      tags: [Capabilities]
-      summary: Get agent capabilities
-      description: Returns the full capability manifest of the agent
-      operationId: getCapabilities
-      responses:
-        '200':
-          description: Agent capabilities
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AgentCapabilities'
-
-  /capabilities/operations:
-    get:
-      tags: [Capabilities]
-      summary: List available operations
-      description: Returns all operations this agent can perform
-      operationId: getOperations
-      parameters:
-        - name: domain
-          in: query
-          description: Filter operations by domain
-          schema:
-            type: string
-            enum:
-              [
-                nlp,
-                vision,
-                reasoning,
-                data,
-                documentation,
-                api-design,
-                validation,
-                orchestration,
-                monitoring,
-                security,
-                compliance,
-                testing,
-                deployment,
-                audio,
-                speech,
-                interaction,
-              ]
-      responses:
-        '200':
-          description: Available operations
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/AgentOperation'
-
-  /execute:
-    post:
-      tags: [Execution]
-      summary: Execute agent operation
-      description: Execute a specific operation with the provided input
-      operationId: executeOperation
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/ExecutionRequest'
-      responses:
-        '200':
-          description: Operation completed successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ExecutionResponse'
-        '202':
-          description: Operation accepted and running asynchronously
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AsyncExecutionResponse'
-        '400':
-          description: Invalid request
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-        '422':
-          description: Validation error
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ValidationErrorResponse'
-
-  /execute/{executionId}:
-    get:
-      tags: [Execution]
-      summary: Get execution status
-      description: Get the status of an asynchronous execution
-      operationId: getExecutionStatus
-      parameters:
-        - name: executionId
-          in: path
-          required: true
-          schema:
-            type: string
-            format: uuid
-      responses:
-        '200':
-          description: Execution status
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ExecutionStatus'
-        '404':
-          description: Execution not found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /status:
-    get:
-      tags: [Lifecycle]
-      summary: Get agent status
-      description: Returns detailed status information about the agent
-      operationId: getStatus
-      responses:
-        '200':
-          description: Agent status
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AgentStatus'
-
-  /lifecycle/start:
-    post:
-      tags: [Lifecycle]
-      summary: Start agent
-      description: Start or restart the agent
-      operationId: startAgent
-      responses:
-        '200':
-          description: Agent started successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/LifecycleResponse'
-        '409':
-          description: Agent is already running
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /lifecycle/stop:
-    post:
-      tags: [Lifecycle]
-      summary: Stop agent
-      description: Gracefully stop the agent
-      operationId: stopAgent
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                graceful:
-                  type: boolean
-                  default: true
-                  description: Whether to stop gracefully
-                timeout:
-                  type: integer
-                  default: 30
-                  description: Timeout in seconds for graceful shutdown
-      responses:
-        '200':
-          description: Agent stopped successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/LifecycleResponse'
-
-  /communicate:
-    post:
-      tags: [Communication]
-      summary: Send message to agent
-      description: Send a message to this agent from another agent
-      operationId: sendMessage
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AgentMessage'
-      responses:
-        '200':
-          description: Message processed successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MessageResponse'
-        '400':
-          description: Invalid message format
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /mcp/capabilities:
-    get:
-      tags: [Model Context Protocol]
-      summary: Get MCP capabilities
-      description: Returns the Model Context Protocol capabilities of this agent
-      operationId: getMcpCapabilities
-      responses:
-        '200':
-          description: MCP capabilities
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/McpCapabilities'
-
-  /mcp/tools:
-    get:
-      tags: [Model Context Protocol]
-      summary: List MCP tools
-      description: Returns all MCP tools available on this agent
-      operationId: getMcpTools
-      responses:
-        '200':
-          description: Available MCP tools
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/McpTool'
-
-  /mcp/tools/{toolName}/call:
-    post:
-      tags: [Model Context Protocol]
-      summary: Call MCP tool
-      description: Execute an MCP tool with the provided arguments
-      operationId: callMcpTool
-      parameters:
-        - name: toolName
-          in: path
-          required: true
-          schema:
-            type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/McpToolCall'
-      responses:
-        '200':
-          description: Tool executed successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/McpToolResponse'
-
-components:
-  schemas:
-    HealthStatus:
-      type: object
-      required: [status, timestamp]
-      properties:
-        status:
-          type: string
-          enum: [healthy, degraded, unhealthy]
-        timestamp:
-          type: string
-          format: date-time
-        version:
-          type: string
-        uptime:
-          type: integer
-          description: Uptime in seconds
-        dependencies:
-          type: object
-          additionalProperties:
-            type: string
-            enum: [healthy, unhealthy]
-
-    LivenessStatus:
-      type: object
-      required: [alive, timestamp]
-      properties:
-        alive:
-          type: boolean
-        timestamp:
-          type: string
-          format: date-time
-        pid:
-          type: integer
-        memory_usage:
-          type: number
-          description: Memory usage in MB
-
-    ReadinessStatus:
-      type: object
-      required: [ready, timestamp]
-      properties:
-        ready:
-          type: boolean
-        timestamp:
-          type: string
-          format: date-time
-        dependencies_ready:
-          type: boolean
-        initialization_complete:
-          type: boolean
-
-    StartupStatus:
-      type: object
-      required: [started, timestamp]
-      properties:
-        started:
-          type: boolean
-        timestamp:
-          type: string
-          format: date-time
-        startup_duration:
-          type: number
-          description: Startup duration in seconds
-
-    AgentCapabilities:
-      type: object
-      required: [agent_id, type, domains, operations, protocols]
-      properties:
-        agent_id:
-          type: string
-        type:
-          type: string
-          enum:
-            [
-              orchestrator,
-              worker,
-              critic,
-              judge,
-              trainer,
-              governor,
-              monitor,
-              integrator,
-              voice,
-            ]
-        subtype:
-          type: string
-          pattern: '^[a-z]+\.[a-z]+$'
-        domains:
-          type: array
-          minItems: 1
-          items:
-            type: string
-            enum:
-              [
-                nlp,
-                vision,
-                reasoning,
-                data,
-                documentation,
-                api-design,
-                validation,
-                orchestration,
-                monitoring,
-                security,
-                compliance,
-                testing,
-                deployment,
-                audio,
-                speech,
-                interaction,
-              ]
-        operations:
-          type: array
-          items:
-            $ref: '#/components/schemas/AgentOperation'
-        protocols:
-          type: object
-          required: [supported, preferred]
-          properties:
-            supported:
-              type: array
-              minItems: 1
-              items:
-                $ref: '#/components/schemas/ProtocolSupport'
-            preferred:
-              type: string
-              enum: [rest, grpc, websocket, mcp, graphql]
-        input_formats:
-          type: array
-          items:
-            type: string
-        output_formats:
-          type: array
-          items:
-            type: string
-        token_efficiency:
-          $ref: '#/components/schemas/TokenEfficiency'
-
-    AgentOperation:
-      type: object
-      required: [name, description]
-      properties:
-        name:
-          type: string
-          pattern: '^[a-z][a-z0-9_]*$'
-        description:
-          type: string
-        input_schema:
-          type: object
-          description: JSON Schema for operation input
-        output_schema:
-          type: object
-          description: JSON Schema for operation output
-        timeout:
-          type: integer
-          minimum: 100
-          maximum: 300000
-          description: Operation timeout in milliseconds
-        domain:
-          type: string
-        async:
-          type: boolean
-          default: false
-
-    ProtocolSupport:
-      type: object
-      required: [name, version]
-      properties:
-        name:
-          type: string
-          enum: [rest, grpc, websocket, mcp, graphql]
-        version:
-          type: string
-        endpoint:
-          type: string
-          format: uri
-        authentication:
-          $ref: '#/components/schemas/AuthenticationConfig'
-        tls:
-          type: boolean
-          default: true
-
-    AuthenticationConfig:
-      type: object
-      required: [type]
-      properties:
-        type:
-          type: string
-          enum: [none, api-key, oauth2, jwt, mtls]
-        config:
-          type: object
-          description: Authentication-specific configuration
-
-    TokenEfficiency:
-      type: object
-      properties:
-        strategies:
-          type: array
-          items:
-            type: string
-            enum:
-              [
-                key-based-context,
-                delta-prompting,
-                tiered-depth,
-                output-only-critique,
-                cacheable-capsules,
-                vector-pre-filters,
-                pre-llm-validation,
-                compression-support,
-                checkpoint-memos,
-                early-exit-logic,
-              ]
-        compression_ratio:
-          type: number
-          minimum: 0
-          maximum: 1
-
-    ExecutionRequest:
-      type: object
-      required: [operation]
-      properties:
-        operation:
-          type: string
-        input:
-          type: object
-          description: Operation-specific input data
-        context:
-          type: object
-          properties:
-            correlation_id:
-              type: string
-            source_agent:
-              type: string
-            trace_id:
-              type: string
-        options:
-          type: object
-          properties:
-            timeout:
-              type: integer
-              minimum: 100
-              maximum: 300000
-            async:
-              type: boolean
-              default: false
-            priority:
-              type: string
-              enum: [low, normal, high, critical]
-              default: normal
-
-    ExecutionResponse:
-      type: object
-      required: [success, result]
-      properties:
-        success:
-          type: boolean
-        result:
-          type: object
-          description: Operation-specific result data
-        metadata:
-          type: object
-          properties:
-            execution_time:
-              type: number
-              description: Execution time in milliseconds
-            tokens_used:
-              type: integer
-            model_used:
-              type: string
-        errors:
-          type: array
-          items:
-            $ref: '#/components/schemas/ExecutionError'
-
-    AsyncExecutionResponse:
-      type: object
-      required: [execution_id, status]
-      properties:
-        execution_id:
-          type: string
-          format: uuid
-        status:
-          type: string
-          enum: [accepted, running]
-        estimated_completion:
-          type: string
-          format: date-time
-
-    ExecutionStatus:
-      type: object
-      required: [execution_id, status]
-      properties:
-        execution_id:
-          type: string
-          format: uuid
-        status:
-          type: string
-          enum: [pending, running, completed, failed, cancelled]
-        progress:
-          type: number
-          minimum: 0
-          maximum: 100
-        result:
-          type: object
-          description: Available when status is completed
-        error:
-          $ref: '#/components/schemas/ExecutionError'
-        started_at:
-          type: string
-          format: date-time
-        completed_at:
-          type: string
-          format: date-time
-
-    ExecutionError:
-      type: object
-      required: [code, message]
-      properties:
-        code:
-          type: string
-        message:
-          type: string
-        details:
-          type: object
-        stack_trace:
-          type: string
-
-    AgentStatus:
-      type: object
-      required: [agent_id, state, health]
-      properties:
-        agent_id:
-          type: string
-        state:
-          type: string
-          enum: [pending, registered, active, suspended, terminated]
-        health:
-          type: string
-          enum: [healthy, degraded, unhealthy, unknown]
-        last_heartbeat:
-          type: string
-          format: date-time
-        registered_at:
-          type: string
-          format: date-time
-        metrics:
-          $ref: '#/components/schemas/AgentMetrics'
-
-    AgentMetrics:
-      type: object
-      properties:
-        requests_handled:
-          type: integer
-        success_rate:
-          type: number
-          minimum: 0
-          maximum: 1
-        avg_response_time:
-          type: integer
-          description: Average response time in milliseconds
-        token_usage:
-          type: integer
-          description: Total tokens consumed
-
-    LifecycleResponse:
-      type: object
-      required: [action, status, timestamp]
-      properties:
-        action:
-          type: string
-          enum: [start, stop, restart]
-        status:
-          type: string
-          enum: [success, failed]
-        timestamp:
-          type: string
-          format: date-time
-        message:
-          type: string
-
-    AgentMessage:
-      type: object
-      required: [from, type, content]
-      properties:
-        from:
-          type: string
-          description: Source agent ID
-        to:
-          type: string
-          description: Target agent ID (optional for broadcasts)
-        type:
-          type: string
-          enum: [request, response, notification, broadcast]
-        content:
-          type: object
-          description: Message content
-        correlation_id:
-          type: string
-        timestamp:
-          type: string
-          format: date-time
-
-    MessageResponse:
-      type: object
-      required: [received, timestamp]
-      properties:
-        received:
-          type: boolean
-        timestamp:
-          type: string
-          format: date-time
-        response:
-          type: object
-          description: Optional response data
-
-    McpCapabilities:
-      type: object
-      required: [version, tools]
-      properties:
-        version:
-          type: string
-          description: MCP protocol version
-        tools:
-          type: object
-          properties:
-            list_changed:
-              type: boolean
-        resources:
-          type: object
-          properties:
-            subscribe:
-              type: boolean
-            list_changed:
-              type: boolean
-
-    McpTool:
-      type: object
-      required: [name, description]
-      properties:
-        name:
-          type: string
-        description:
-          type: string
-        input_schema:
-          type: object
-          description: JSON Schema for tool input
-
-    McpToolCall:
-      type: object
-      required: [arguments]
-      properties:
-        arguments:
-          type: object
-          description: Tool-specific arguments
-
-    McpToolResponse:
-      type: object
-      required: [content]
-      properties:
-        content:
-          type: array
-          items:
-            type: object
-            properties:
-              type:
-                type: string
-                enum: [text, image, resource]
-              text:
-                type: string
-              data:
-                type: string
-                format: base64
-              uri:
-                type: string
-                format: uri
-        is_error:
-          type: boolean
-          default: false
-
-    ErrorResponse:
-      type: object
-      required: [error, message, timestamp]
-      properties:
-        error:
-          type: string
-        message:
-          type: string
-        timestamp:
-          type: string
-          format: date-time
-        details:
-          type: object
-        trace_id:
-          type: string
-
-    ValidationErrorResponse:
-      type: object
-      required: [error, message, validation_errors]
-      properties:
-        error:
-          type: string
-          enum: [validation_error]
-        message:
-          type: string
-        validation_errors:
-          type: array
-          items:
-            type: object
-            properties:
-              field:
-                type: string
-              code:
-                type: string
-              message:
-                type: string
-        timestamp:
-          type: string
-          format: date-time
-
-  securitySchemes:
-    BearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-    ApiKeyAuth:
-      type: apiKey
-      in: header
-      name: X-API-Key
-    OAuth2:
-      type: oauth2
-      flows:
-        clientCredentials:
-          tokenUrl: /oauth/token
-          scopes:
-            agent:read: Read agent information
-            agent:execute: Execute agent operations
-            agent:admin: Full agent administration
-
-security:
-  - BearerAuth: []
-  - ApiKeyAuth: []
-  - OAuth2: [agent:read, agent:execute]