@bluefly/openstandardagents 0.4.3 → 0.4.5

package/templates/validators/coordination-consistency.ossa.yaml

@@ -0,0 +1,160 @@
+apiVersion: ossa/v0.4.4
+kind: Validator
+metadata:
+  name: coordination-consistency-validator
+  version: 1.0.0
+  description: Validates coordination patterns and agent architecture consistency
+  agentType: validator
+  agentKind: semantic
+  tags:
+    - coordination
+    - architecture
+    - patterns
+
+spec:
+  validates:
+    targetTypes:
+      - all
+    phases:
+      - semantic
+
+  rules:
+    # Pattern: swarm requires agents array
+    - id: swarm-requires-agents
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: swarm
+      and:
+        path: spec.agents
+        exists: false
+      then:
+        enforcement: error
+        message: "Swarm pattern requires spec.agents array with multiple agent definitions"
+        rationale: "Swarm coordination pattern requires at least 2 agents for collaboration"
+        fixes:
+          - action: add
+            path: spec.agents
+            value: []
+            impact: "+0.30 compatibility"
+            effort: medium
+        documentation: "https://openstandardagents.org/docs/patterns/swarm"
+
+    # Pattern: pipeline requires executionModel
+    - id: pipeline-requires-execution-model
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: pipeline
+      and:
+        path: metadata.agentArchitecture.runtime.executionModel
+        exists: false
+      then:
+        enforcement: warning
+        message: "Pipeline pattern should specify executionModel (sequential, parallel, or conditional)"
+        fixes:
+          - action: add
+            path: metadata.agentArchitecture.runtime.executionModel
+            value: sequential
+            impact: "+0.10 clarity"
+            effort: low
+
+    # Pattern: single with multiple agents is inconsistent
+    - id: single-pattern-multiple-agents
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: single
+      and:
+        path: spec.agents
+        exists: true
+      then:
+        enforcement: warning
+        message: "Pattern 'single' declared but spec.agents array found. Consider pattern: 'swarm' or 'pipeline'"
+        rationale: "Single pattern implies one agentic loop, not coordination of multiple agents"
+        fixes:
+          - action: change
+            path: metadata.agentArchitecture.pattern
+            value: swarm
+            impact: "+0.15 consistency"
+            effort: low
+          - action: remove
+            path: spec.agents
+            impact: "+0.10 consistency"
+            effort: medium
+
+    # agentKind: orchestrator should have coordination config
+    - id: orchestrator-needs-coordination
+      when:
+        path: metadata.agentKind
+        equals: orchestrator
+      and:
+        path: metadata.agentArchitecture.coordination
+        exists: false
+      then:
+        enforcement: warning
+        message: "Orchestrator agents should declare agentArchitecture.coordination config"
+        rationale: "Orchestrators coordinate multiple agents and should specify their coordination strategy"
+        fixes:
+          - action: add
+            path: metadata.agentArchitecture.coordination
+            value:
+              style: centralized
+              handoffStrategy: sequential
+            impact: "+0.15 observability"
+            effort: low
+
+    # agentKind: worker with coordination is unusual
+    - id: worker-with-coordination
+      when:
+        path: metadata.agentKind
+        equals: worker
+      and:
+        path: metadata.agentArchitecture.coordination
+        exists: true
+      then:
+        enforcement: info
+        message: "Workers typically don't coordinate other agents. Consider agentKind: 'orchestrator' if this agent manages others."
+        rationale: "Workers execute tasks, orchestrators coordinate agents"
+
+    # Hierarchical pattern requires agentKind: orchestrator or supervisor
+    - id: hierarchical-requires-supervisor
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: hierarchical
+      and:
+        path: metadata.agentKind
+        equals: worker
+      then:
+        enforcement: warning
+        message: "Hierarchical pattern typically requires agentKind: 'orchestrator' or 'supervisor', not 'worker'"
+        fixes:
+          - action: change
+            path: metadata.agentKind
+            value: orchestrator
+            impact: "+0.15 consistency"
+            effort: low
+
+    # Parallel coordination requires scalability config
+    - id: parallel-coordination-needs-scalability
+      when:
+        path: metadata.agentArchitecture.coordination.style
+        equals: parallel
+      and:
+        path: metadata.agentArchitecture.runtime.scalability
+        exists: false
+      then:
+        enforcement: warning
+        message: "Parallel coordination should specify runtime.scalability (horizontal or vertical)"
+        fixes:
+          - action: add
+            path: metadata.agentArchitecture.runtime.scalability
+            value: horizontal
+            impact: "+0.10 completeness"
+            effort: low
+
+  coordination:
+    composable: true
+    operators:
+      - ">>"  # Can run after other validators
+      - "<||>"  # Can run in parallel
+
+  dependencies:
+    - capability-compatibility-validator  # Run after capability checks

package/templates/validators/pattern-requirements.ossa.yaml

@@ -0,0 +1,182 @@
+apiVersion: ossa/v0.4.4
+kind: Validator
+metadata:
+  name: pattern-requirements-validator
+  version: 1.0.0
+  description: Validates architecture patterns meet required constraints
+  agentType: validator
+  agentKind: semantic
+  tags:
+    - patterns
+    - architecture
+    - requirements
+
+spec:
+  validates:
+    targetTypes:
+      - all
+    phases:
+      - semantic
+
+  rules:
+    # Graph pattern requires workflow definition
+    - id: graph-requires-workflow
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: graph
+      and:
+        path: spec.workflow
+        exists: false
+      then:
+        enforcement: error
+        message: "Graph pattern requires spec.workflow with nodes and edges"
+        rationale: "Graph patterns represent DAG workflows and need explicit node/edge definitions"
+        fixes:
+          - action: add
+            path: spec.workflow
+            value:
+              nodes: []
+              edges: []
+            impact: "+0.30 compatibility"
+            effort: high
+        documentation: "https://openstandardagents.org/docs/patterns/graph"
+
+    # Pipeline pattern should have stages
+    - id: pipeline-should-have-stages
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: pipeline
+      and:
+        path: spec.stages
+        exists: false
+      then:
+        enforcement: warning
+        message: "Pipeline pattern should define spec.stages array"
+        rationale: "Pipelines consist of sequential stages (A → B → C)"
+        fixes:
+          - action: add
+            path: spec.stages
+            value: []
+            impact: "+0.20 clarity"
+            effort: medium
+
+    # Swarm pattern requires at least 2 agents
+    - id: swarm-minimum-agents
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: swarm
+      and:
+        path: spec.agents
+        exists: true
+      # Note: Can't check array length in JSON Schema validation
+      # This rule documents the requirement for runtime validation
+      then:
+        enforcement: info
+        message: "Swarm pattern requires at least 2 agents in spec.agents array"
+        rationale: "Single agent should use pattern: 'single', not swarm"
+        documentation: "https://openstandardagents.org/docs/patterns/swarm"
+
+    # Hierarchical pattern requires manager/worker structure
+    - id: hierarchical-requires-structure
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: hierarchical
+      and:
+        path: spec.hierarchy
+        exists: false
+      then:
+        enforcement: warning
+        message: "Hierarchical pattern should define spec.hierarchy structure"
+        rationale: "Hierarchical patterns organize agents in manager/worker layers"
+        fixes:
+          - action: add
+            path: spec.hierarchy
+            value:
+              levels: 2
+              manager: null
+              workers: []
+            impact: "+0.20 clarity"
+            effort: medium
+
+    # Single pattern with streaming should declare capability
+    - id: single-streaming-capability
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: single
+      and:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: streaming
+      and:
+        path: metadata.agentArchitecture.capabilities
+        contains: streaming
+        exists: false
+      then:
+        enforcement: warning
+        message: "Streaming executionModel should include 'streaming' in capabilities"
+        fixes:
+          - action: add
+            path: metadata.agentArchitecture.capabilities
+            value: streaming
+            impact: "+0.10 consistency"
+            effort: low
+
+    # Event-driven execution requires event handlers
+    - id: event-driven-requires-handlers
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: event-driven
+      and:
+        path: spec.eventHandlers
+        exists: false
+      then:
+        enforcement: warning
+        message: "Event-driven executionModel should define spec.eventHandlers"
+        rationale: "Event-driven agents respond to events and need handler definitions"
+        fixes:
+          - action: add
+            path: spec.eventHandlers
+            value: []
+            impact: "+0.15 completeness"
+            effort: medium
+
+    # Batch execution should have batch config
+    - id: batch-requires-config
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: batch
+      and:
+        path: spec.batch
+        exists: false
+      then:
+        enforcement: info
+        message: "Batch executionModel could specify spec.batch configuration (size, interval, etc.)"
+        rationale: "Batch processing often needs size limits and scheduling parameters"
+
+    # Real-time execution with single-instance scalability
+    - id: realtime-scalability-warning
+      when:
+        path: metadata.agentArchitecture.runtime.executionModel
+        equals: realtime
+      and:
+        path: metadata.agentArchitecture.runtime.scalability
+        equals: single-instance
+      then:
+        enforcement: warning
+        message: "Real-time executionModel with single-instance scalability may bottleneck. Consider horizontal scaling."
+        rationale: "Real-time workloads often need horizontal scaling for high availability"
+        fixes:
+          - action: change
+            path: metadata.agentArchitecture.runtime.scalability
+            value: horizontal
+            impact: "+0.15 performance"
+            effort: medium
+
+  coordination:
+    composable: true
+    operators:
+      - ">>"
+      - "<||>"
+
+  dependencies:
+    - capability-compatibility-validator
+    - coordination-consistency-validator

package/templates/validators/transport-compatibility.ossa.yaml

@@ -0,0 +1,185 @@
+apiVersion: ossa/v0.4.4
+kind: Validator
+metadata:
+  name: transport-compatibility-validator
+  version: 1.0.0
+  description: Validates transport protocol configuration and compatibility
+  agentType: validator
+  agentKind: platform
+  tags:
+    - transport
+    - networking
+    - protocols
+
+spec:
+  validates:
+    targetTypes:
+      - all
+    phases:
+      - platform
+
+  rules:
+    # KAGENT prefers gRPC transport
+    - id: kagent-grpc-preferred
+      when:
+        path: metadata.agentType
+        equals: kagent
+      and:
+        path: spec.transport.protocol
+        exists: false
+      then:
+        enforcement: info
+        message: "KAGENT agents typically use gRPC transport for Kubernetes-native communication"
+        rationale: "gRPC provides efficient binary protocol with bidirectional streaming, well-suited for K8s"
+        fixes:
+          - action: add
+            path: spec.transport
+            value:
+              protocol: grpc
+              host: "0.0.0.0"
+              port: 50051
+            impact: "+0.10 performance"
+            effort: low
+        documentation: "https://openstandardagents.org/docs/agent-types/kagent"
+
+    # Claude/OpenAI typically use HTTP/REST
+    - id: llm-agents-http-transport
+      when:
+        path: metadata.agentType
+        equals: claude
+      or:
+        path: metadata.agentType
+        equals: openai
+      and:
+        path: spec.transport
+        exists: false
+      then:
+        enforcement: info
+        message: "LLM agents (Claude, OpenAI) typically use HTTP/REST transport"
+        rationale: "Provider APIs use HTTP REST, no need for custom transport unless coordinating with other agents"
+
+    # Streaming capability requires appropriate transport
+    - id: streaming-transport-requirements
+      when:
+        path: metadata.agentArchitecture.capabilities
+        contains: streaming
+      and:
+        path: spec.transport.protocol
+        equals: http
+      and:
+        path: spec.transport.streaming
+        exists: false
+      then:
+        enforcement: warning
+        message: "Streaming capability with HTTP transport should configure spec.transport.streaming (SSE or WebSocket)"
+        rationale: "HTTP streaming requires Server-Sent Events (SSE) or WebSocket protocol"
+        fixes:
+          - action: add
+            path: spec.transport.streaming
+            value:
+              type: sse
+            impact: "+0.10 completeness"
+            effort: low
+
+    # gRPC transport should specify protobuf definitions
+    - id: grpc-requires-protobuf
+      when:
+        path: spec.transport.protocol
+        equals: grpc
+      and:
+        path: spec.transport.protobuf
+        exists: false
+      then:
+        enforcement: warning
+        message: "gRPC transport should reference protobuf definitions (spec.transport.protobuf)"
+        fixes:
+          - action: add
+            path: spec.transport.protobuf
+            value:
+              package: agent.v1
+              service: AgentService
+            impact: "+0.10 completeness"
+            effort: medium
+
+    # Authentication should be configured for production
+    - id: production-requires-auth
+      when:
+        path: metadata.labels.environment
+        equals: production
+      and:
+        path: spec.transport.authentication
+        exists: false
+      then:
+        enforcement: error
+        message: "Production agents must configure transport authentication"
+        rationale: "Unauthenticated transports in production are a security risk"
+        fixes:
+          - action: add
+            path: spec.transport.authentication
+            value:
+              type: bearer
+              tokenRotation: enabled
+            impact: "+0.40 security"
+            effort: medium
+        documentation: "https://openstandardagents.org/docs/security/authentication"
+
+    # TLS should be enabled for production
+    - id: production-requires-tls
+      when:
+        path: metadata.labels.environment
+        equals: production
+      and:
+        path: spec.transport.tls
+        equals: false
+      then:
+        enforcement: error
+        message: "Production agents must enable TLS/SSL encryption"
+        rationale: "Unencrypted transport in production exposes sensitive data"
+        fixes:
+          - action: change
+            path: spec.transport.tls
+            value: true
+            impact: "+0.35 security"
+            effort: low
+
+    # Port conflicts: Check common ports
+    - id: avoid-privileged-ports
+      when:
+        path: spec.transport.port
+        # Can't do numeric comparison in JSON Schema
+        # This is a reminder for runtime validation
+      then:
+        enforcement: info
+        message: "Avoid privileged ports (< 1024) unless necessary. Common agent ports: 8080 (HTTP), 50051 (gRPC)"
+        rationale: "Privileged ports require root access, complicating deployment"
+        documentation: "https://openstandardagents.org/docs/deployment/ports"
+
+    # Swarm agents need agent-to-agent transport
+    - id: swarm-requires-a2a-transport
+      when:
+        path: metadata.agentArchitecture.pattern
+        equals: swarm
+      and:
+        path: spec.transport.a2a
+        exists: false
+      then:
+        enforcement: warning
+        message: "Swarm pattern should configure agent-to-agent transport (spec.transport.a2a)"
+        rationale: "Swarm agents communicate directly and need A2A transport config"
+        fixes:
+          - action: add
+            path: spec.transport.a2a
+            value:
+              protocol: grpc
+              discovery: dns
+            impact: "+0.20 coordination"
+            effort: medium
+
+  coordination:
+    composable: true
+    operators:
+      - ">>"
+      - "<||>"
+
+  dependencies:
+    - capability-compatibility-validator

package/.wiki-config.json

@@ -1,24 +0,0 @@
-{
-  "PROJECT_NAME": "@bluefly/openstandardagents",
-  "PROJECT_DESCRIPTION": "OSSA - Open Standard for Scalable AI Agents. A specification standard for AI agents (like OpenAPI for REST APIs). NOT a framework.",
-  "VERSION": "0.3.0",
-  "STATUS": "Active",
-  "LICENSE": "Apache-2.0",
-  "KEY_FEATURES": "- OSSA v0.3.0 specification\n- Type-safe TypeScript validation\n- OpenAPI 3.1 specifications\n- Reference implementations\n- Agent-to-Agent messaging\n- Web-native protocols",
-  "REPO_URL": "https://gitlab.com/blueflyio/openstandardagents",
-  "GITLAB_ISSUES_URL": "https://gitlab.com/blueflyio/openstandardagents/-/issues",
-  "DOCS_URL": "https://gitlab.com/blueflyio/openstandardagents/-/wikis/home",
-  "TEAM_CONTACT": "${GIT_AUTHOR_EMAIL:-oss@bluefly.io}",
-  "PREREQUISITES": "- Node.js 20+\n- TypeScript 5.9+",
-  "INSTALL_COMMAND": "npm install",
-  "START_COMMAND": "npm run dev",
-  "VERIFY_COMMAND": "npm run test",
-  "BACKEND_STACK": "- TypeScript 5.9+\n- Zod - Schema validation\n- AJV - JSON Schema validation",
-  "FRONTEND_STACK": "N/A",
-  "INFRASTRUCTURE_STACK": "- Docker\n- GitLab CI/CD",
-  "API_BASE_URL": "N/A",
-  "OPENAPI_URL": "https://gitlab.com/blueflyio/openstandardagents/-/tree/main/openapi",
-  "UNIT_TEST_COMMAND": "npm run test:unit",
-  "LINT_COMMAND": "npm run lint",
-  "FORMAT_COMMAND": "npm run format"
-}