@bluefly/openstandardagents 0.4.8 → 0.5.0

package/openapi/core/unified-agent-gateway.openapi.yaml

@@ -4,7 +4,7 @@ info:
   version: 0.3.3
   description: |
     **Single Entry Point for All LLM Platform Agents**
-    
+
     This gateway provides a unified OpenAPI interface for:
     - OSSA-compliant agents (validation, deployment, orchestration)
     - Drupal llm-platform (content, users, sites, data management)
@@ -13,7 +13,7 @@ info:
     - Langflow/LangChain/K-Agent workflows
     - BuildKit (agent lifecycle management)
     - GitLab CI/CD orchestration
-    
+
     **Architecture**:
     - Protocol: HTTP/REST + gRPC (agent-mesh)
     - Auth: API Key + JWT (GitLab SSO)
@@ -21,25 +21,20 @@ info:
     - Tracing: Phoenix (all requests)
     - Metrics: Prometheus
     - Storage: Drupal llm-platform (single source of truth)
-
   contact:
     name: LLM Platform Team
     url: https://github.com/blueflyio/openstandardagents
-  
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
-
 servers:
   - url: https://gateway.agent-buildkit.orb.local/api/v1
     description: Production
   - url: http://localhost:8080/api/v1
     description: Local development (Orbstack)
-
 security:
   - ApiKeyAuth: []
   - GitLabJWT: []
-
 tags:
   - name: agents
     description: Agent lifecycle management (create, deploy, scale, delete)
@@ -53,15 +48,11 @@ tags:
     description: GitLab CI/CD orchestration
   - name: registry
     description: Service discovery and health monitoring
-
 paths:
-  # =================================================================
-  # AGENTS - Unified Agent Management
-  # =================================================================
-  
   /agents:
     post:
-      tags: [agents]
+      tags:
+        - agents
       summary: Create and deploy new agent
       description: |
         Creates an OSSA-compliant agent and deploys to K8s via Helm.
@@ -72,105 +63,123 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateAgentRequest'
+              $ref: "#/components/schemas/CreateAgentRequest"
       responses:
-        '201':
+        "201":
           description: Agent created and deployed
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AgentResponse'
-    
+                $ref: "#/components/schemas/AgentResponse"
+      x-ossa-capability: gateway-create-agent
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
     get:
-      tags: [agents]
+      tags:
+        - agents
       summary: List all agents
       operationId: listAgents
       parameters:
-        - $ref: '#/components/parameters/Namespace'
-        - $ref: '#/components/parameters/Status'
-        - $ref: '#/components/parameters/Framework'
+        - $ref: "#/components/parameters/Namespace"
+        - $ref: "#/components/parameters/Status"
+        - $ref: "#/components/parameters/Framework"
       responses:
-        '200':
+        "200":
           description: List of agents
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AgentList'
-
+                $ref: "#/components/schemas/AgentList"
+      x-ossa-capability: gateway-list-agents
+      description: List all agents
   /agents/{agentId}:
     get:
-      tags: [agents]
+      tags:
+        - agents
       summary: Get agent details
       operationId: getAgent
       parameters:
-        - $ref: '#/components/parameters/AgentId'
+        - $ref: "#/components/parameters/AgentId"
       responses:
-        '200':
+        "200":
           description: Agent details
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AgentDetails'
-    
+                $ref: "#/components/schemas/AgentDetails"
+      x-ossa-capability: gateway-get-agent
+      description: Get agent details
     put:
-      tags: [agents]
+      tags:
+        - agents
       summary: Update agent
       operationId: updateAgent
       parameters:
-        - $ref: '#/components/parameters/AgentId'
+        - $ref: "#/components/parameters/AgentId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UpdateAgentRequest'
+              $ref: "#/components/schemas/UpdateAgentRequest"
       responses:
-        '200':
+        "200":
           description: Agent updated
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AgentResponse'
-    
+                $ref: "#/components/schemas/AgentResponse"
+      x-ossa-capability: gateway-update-agent
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      description: Update agent
     delete:
-      tags: [agents]
+      tags:
+        - agents
       summary: Delete agent
       operationId: deleteAgent
       parameters:
-        - $ref: '#/components/parameters/AgentId'
+        - $ref: "#/components/parameters/AgentId"
       responses:
-        '204':
+        "204":
           description: Agent deleted
-
+      x-ossa-capability: gateway-delete-agent
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      description: Delete agent
   /agents/{agentId}/execute:
     post:
-      tags: [agents]
+      tags:
+        - agents
       summary: Execute agent task
       description: Send task to agent and get response
       operationId: executeAgentTask
       parameters:
-        - $ref: '#/components/parameters/AgentId'
+        - $ref: "#/components/parameters/AgentId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/AgentTaskRequest'
+              $ref: "#/components/schemas/AgentTaskRequest"
       responses:
-        '200':
+        "200":
           description: Task executed
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/AgentTaskResponse'
-
-  # =================================================================
-  # DRUPAL - Single Source of Truth
-  # =================================================================
-  
+                $ref: "#/components/schemas/AgentTaskResponse"
+      x-ossa-capability: gateway-execute-agent-task
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /drupal/content:
     post:
-      tags: [drupal]
+      tags:
+        - drupal
       summary: Create Drupal content
       description: Create content node via llm-platform API
       operationId: createDrupalContent
@@ -179,17 +188,21 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/DrupalContentRequest'
+              $ref: "#/components/schemas/DrupalContentRequest"
       responses:
-        '201':
+        "201":
           description: Content created
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DrupalContentResponse'
-    
+                $ref: "#/components/schemas/DrupalContentResponse"
+      x-ossa-capability: gateway-create-drupal-content
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
     get:
-      tags: [drupal]
+      tags:
+        - drupal
       summary: Query Drupal content
       operationId: queryDrupalContent
       parameters:
@@ -201,20 +214,25 @@ paths:
           in: query
           schema:
             type: string
-            enum: [published, draft, archived]
+            enum:
+              - published
+              - draft
+              - archived
       responses:
-        '200':
+        "200":
           description: Content list
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/DrupalContentResponse'
-
+                  $ref: "#/components/schemas/DrupalContentResponse"
+      x-ossa-capability: gateway-query-drupal-content
+      description: Query Drupal content
   /drupal/users:
     post:
-      tags: [drupal]
+      tags:
+        - drupal
       summary: Create Drupal user
       operationId: createDrupalUser
       requestBody:
@@ -222,22 +240,29 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/DrupalUserRequest'
+              $ref: "#/components/schemas/DrupalUserRequest"
       responses:
-        '201':
+        "201":
           description: User created
-    
+      x-ossa-capability: gateway-create-drupal-user
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      description: Create Drupal user
     get:
-      tags: [drupal]
+      tags:
+        - drupal
       summary: List users
       operationId: listDrupalUsers
       responses:
-        '200':
+        "200":
           description: User list
-
+      x-ossa-capability: gateway-list-drupal-users
+      description: List users
   /drupal/sites:
     post:
-      tags: [drupal]
+      tags:
+        - drupal
       summary: Build new Drupal site
       description: Agent creates complete Drupal site with modules/config
       operationId: buildDrupalSite
@@ -246,22 +271,22 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/DrupalSiteRequest'
+              $ref: "#/components/schemas/DrupalSiteRequest"
       responses:
-        '202':
+        "202":
           description: Site creation started
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DrupalJobResponse'
-
-  # =================================================================
-  # WORKFLOWS - Langflow/LangChain/K-Agent
-  # =================================================================
-  
+                $ref: "#/components/schemas/DrupalJobResponse"
+      x-ossa-capability: gateway-build-drupal-site
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /workflows:
     post:
-      tags: [workflows]
+      tags:
+        - workflows
       summary: Create workflow
       description: Create Langflow or LangChain workflow
       operationId: createWorkflow
@@ -270,13 +295,17 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/WorkflowRequest'
+              $ref: "#/components/schemas/WorkflowRequest"
       responses:
-        '201':
+        "201":
           description: Workflow created
-    
+      x-ossa-capability: gateway-create-workflow
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
     get:
-      tags: [workflows]
+      tags:
+        - workflows
       summary: List workflows
       operationId: listWorkflows
       parameters:
@@ -284,14 +313,19 @@ paths:
           in: query
           schema:
             type: string
-            enum: [langflow, langchain, kagent]
+            enum:
+              - langflow
+              - langchain
+              - kagent
       responses:
-        '200':
+        "200":
           description: Workflow list
-
+      x-ossa-capability: gateway-list-workflows
+      description: List workflows
   /workflows/{workflowId}/execute:
     post:
-      tags: [workflows]
+      tags:
+        - workflows
       summary: Execute workflow
       operationId: executeWorkflow
       parameters:
@@ -311,16 +345,17 @@ paths:
                   type: object
                   additionalProperties: true
       responses:
-        '200':
+        "200":
           description: Workflow executed
-
-  # =================================================================
-  # STUDIO - Mobile API for Remote Coding
-  # =================================================================
-  
+      x-ossa-capability: gateway-execute-workflow
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      description: Execute workflow
   /studio/sessions:
     post:
-      tags: [studio]
+      tags:
+        - studio
       summary: Create remote coding session
       description: |
         Creates coding session accessible from iOS/CarPlay.
@@ -331,26 +366,32 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/StudioSessionRequest'
+              $ref: "#/components/schemas/StudioSessionRequest"
       responses:
-        '201':
+        "201":
           description: Session created
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/StudioSessionResponse'
-    
+                $ref: "#/components/schemas/StudioSessionResponse"
+      x-ossa-capability: gateway-create-studio-session
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
     get:
-      tags: [studio]
+      tags:
+        - studio
       summary: List active sessions
       operationId: listStudioSessions
       responses:
-        '200':
+        "200":
           description: Active sessions
-
+      x-ossa-capability: gateway-list-studio-sessions
+      description: List active sessions
   /studio/sessions/{sessionId}/tasks:
     post:
-      tags: [studio]
+      tags:
+        - studio
       summary: Queue task for agent
       description: Queue coding task to run while you're mobile
       operationId: queueStudioTask
@@ -365,18 +406,18 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/StudioTaskRequest'
+              $ref: "#/components/schemas/StudioTaskRequest"
       responses:
-        '202':
+        "202":
           description: Task queued
-
-  # =================================================================
-  # GITLAB - CI/CD Orchestration
-  # =================================================================
-  
+      x-ossa-capability: gateway-queue-studio-task
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
   /gitlab/pipelines:
     post:
-      tags: [gitlab]
+      tags:
+        - gitlab
       summary: Trigger pipeline for project
       operationId: triggerPipeline
       requestBody:
@@ -384,22 +425,29 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/GitLabPipelineRequest'
+              $ref: "#/components/schemas/GitLabPipelineRequest"
       responses:
-        '202':
+        "202":
           description: Pipeline triggered
-    
+      x-ossa-capability: gateway-trigger-pipeline
+      x-ossa-autonomy:
+        level: supervised
+        approval_required: true
+      description: Trigger pipeline for project
     get:
-      tags: [gitlab]
+      tags:
+        - gitlab
       summary: List pipelines
       operationId: listPipelines
       responses:
-        '200':
+        "200":
           description: Pipeline list
-
+      x-ossa-capability: gateway-list-pipelines
+      description: List pipelines
   /gitlab/packages:
     get:
-      tags: [gitlab]
+      tags:
+        - gitlab
       summary: List available packages
       description: Query package registry
       operationId: listGitLabPackages
@@ -410,22 +458,19 @@ paths:
             type: string
             example: "@llm"
       responses:
-        '200':
+        "200":
           description: Package list
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/GitLabPackage'
-
-  # =================================================================
-  # REGISTRY - Service Discovery
-  # =================================================================
-  
+                  $ref: "#/components/schemas/GitLabPackage"
+      x-ossa-capability: gateway-list-git-lab-packages
   /registry/discover:
     get:
-      tags: [registry]
+      tags:
+        - registry
       summary: Discover services
       description: Query agent-router for available services/agents
       operationId: discoverServices
@@ -439,27 +484,25 @@ paths:
           schema:
             type: string
       responses:
-        '200':
+        "200":
           description: Discovered services
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ServiceEndpoint'
-
+                  $ref: "#/components/schemas/ServiceEndpoint"
+      x-ossa-capability: gateway-discover-services
 components:
   securitySchemes:
     ApiKeyAuth:
       type: apiKey
       in: header
       name: X-API-Key
-    
     GitLabJWT:
       type: http
       scheme: bearer
       bearerFormat: JWT
-
   parameters:
     AgentId:
       name: agentId
@@ -467,28 +510,32 @@ components:
       required: true
       schema:
         type: string
-    
     Namespace:
       name: namespace
       in: query
       schema:
         type: string
         default: agents
-    
     Status:
       name: status
       in: query
       schema:
         type: string
-        enum: [running, stopped, error]
-    
+        enum:
+          - running
+          - stopped
+          - error
     Framework:
       name: framework
       in: query
       schema:
         type: string
-        enum: [ossa, langflow, langchain, kagent, drupal]
-
+        enum:
+          - ossa
+          - langflow
+          - langchain
+          - kagent
+          - drupal
   schemas:
     CreateAgentRequest:
       type: object
@@ -500,10 +547,13 @@ components:
           type: string
           format: uri
           description: URL to OSSA manifest in GitLab
-          example: "https://github.com/blueflyio/openstandardagents/blob/main/examples/getting-started/hello-world-complete.ossa.yaml"
+          example: https://github.com/blueflyio/openstandardagents/blob/main/examples/getting-started/hello-world-complete.ossa.yaml
         deployment_target:
           type: string
-          enum: [kubernetes, docker, serverless]
+          enum:
+            - kubernetes
+            - docker
+            - serverless
         namespace:
           type: string
           default: agents
@@ -514,7 +564,6 @@ components:
           type: string
           description: GitLab package to use (if available)
           example: "@llm/supercali-fragilisticagent@1.0.0"
-
     AgentResponse:
       type: object
       properties:
@@ -524,7 +573,10 @@ components:
           type: string
         status:
           type: string
-          enum: [deploying, running, error]
+          enum:
+            - deploying
+            - running
+            - error
         endpoints:
           type: object
           properties:
@@ -542,17 +594,15 @@ components:
           format: uri
         helm_release:
           type: string
-
     AgentList:
       type: object
       properties:
         agents:
           type: array
           items:
-            $ref: '#/components/schemas/AgentSummary'
+            $ref: "#/components/schemas/AgentSummary"
         total:
           type: integer
-
     AgentSummary:
       type: object
       properties:
@@ -566,10 +616,9 @@ components:
           type: string
         namespace:
           type: string
-
     AgentDetails:
       allOf:
-        - $ref: '#/components/schemas/AgentResponse'
+        - $ref: "#/components/schemas/AgentResponse"
         - type: object
           properties:
             ossa_manifest:
@@ -580,7 +629,6 @@ components:
               type: array
               items:
                 type: object
-
     UpdateAgentRequest:
       type: object
       properties:
@@ -590,7 +638,6 @@ components:
           type: string
         helm_values:
           type: object
-
     AgentTaskRequest:
       type: object
       required:
@@ -606,7 +653,6 @@ components:
         async:
           type: boolean
           default: false
-
     AgentTaskResponse:
       type: object
       properties:
@@ -614,7 +660,11 @@ components:
           type: string
         status:
           type: string
-          enum: [queued, running, completed, failed]
+          enum:
+            - queued
+            - running
+            - completed
+            - failed
         output:
           type: object
           additionalProperties: true
@@ -622,8 +672,6 @@ components:
           type: array
           items:
             type: object
-
-    # Drupal Schemas
     DrupalContentRequest:
       type: object
       required:
@@ -642,9 +690,10 @@ components:
           additionalProperties: true
         status:
           type: string
-          enum: [published, draft]
+          enum:
+            - published
+            - draft
           default: draft
-
     DrupalContentResponse:
       type: object
       properties:
@@ -662,7 +711,6 @@ components:
         created:
           type: string
           format: date-time
-
     DrupalUserRequest:
       type: object
       required:
@@ -678,7 +726,6 @@ components:
           type: array
           items:
             type: string
-
     DrupalSiteRequest:
       type: object
       required:
@@ -695,7 +742,6 @@ components:
           type: string
         config:
           type: object
-
     DrupalJobResponse:
       type: object
       properties:
@@ -706,8 +752,6 @@ components:
         gitlab_pipeline:
           type: string
           format: uri
-
-    # Workflow Schemas
     WorkflowRequest:
       type: object
       required:
@@ -716,7 +760,10 @@ components:
       properties:
         framework:
           type: string
-          enum: [langflow, langchain, kagent]
+          enum:
+            - langflow
+            - langchain
+            - kagent
         definition:
           type: object
           additionalProperties: true
@@ -725,8 +772,6 @@ components:
           items:
             type: string
           description: Agent IDs to include in workflow
-
-    # Studio Mobile API Schemas
     StudioSessionRequest:
       type: object
       required:
@@ -735,14 +780,17 @@ components:
       properties:
         device_type:
           type: string
-          enum: [ios, ipad, carplay, watch]
+          enum:
+            - ios
+            - ipad
+            - carplay
+            - watch
         repository:
           type: string
           description: GitLab repository URL
         branch:
           type: string
           default: development
-
     StudioSessionResponse:
       type: object
       properties:
@@ -758,7 +806,6 @@ components:
         expires_at:
           type: string
           format: date-time
-
     StudioTaskRequest:
       type: object
       required:
@@ -767,7 +814,11 @@ components:
       properties:
         task_type:
           type: string
-          enum: [code, test, deploy, review]
+          enum:
+            - code
+            - test
+            - deploy
+            - review
         description:
           type: string
         files:
@@ -777,8 +828,6 @@ components:
         agent_id:
           type: string
           description: Specific agent to use (optional)
-
-    # GitLab Schemas
     GitLabPipelineRequest:
       type: object
       required:
@@ -795,7 +844,6 @@ components:
           type: object
           additionalProperties:
             type: string
-
     GitLabPackage:
       type: object
       properties:
@@ -805,12 +853,13 @@ components:
           type: string
         package_type:
           type: string
-          enum: [npm, python, generic]
+          enum:
+            - npm
+            - python
+            - generic
         url:
           type: string
           format: uri
-
-    # Registry Schemas
     ServiceEndpoint:
       type: object
       properties:
@@ -827,7 +876,22 @@ components:
             type: string
         health:
           type: string
-          enum: [healthy, degraded, unhealthy]
+          enum:
+            - healthy
+            - degraded
+            - unhealthy
         framework:
           type: string
-
+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: unified-agent-gateway
+    type: gateway