@bluefly/openstandardagents 0.1.9

package/README.md

@@ -0,0 +1,559 @@
+# OSSA - Open Standard for Scalable Agents
+
+[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-orange.svg)](src/api/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+## Executive Summary
+
+The Open Standard for Scalable Agents (OSSA) provides a comprehensive specification framework for building, deploying, and orchestrating autonomous AI agents at enterprise scale. OSSA defines standardized interfaces, communication protocols, and governance models that enable seamless interoperability between heterogeneous agent systems.
+
+## Technical Overview
+
+OSSA establishes a vendor-neutral, technology-agnostic standard for agent development, addressing critical challenges in multi-agent system architecture:
+
+- **Interoperability**: Standardized APIs enabling cross-platform agent communication
+- **Scalability**: Horizontal scaling patterns supporting millions of concurrent agents
+- **Governance**: Built-in compliance, security, and audit capabilities
+- **Observability**: Comprehensive telemetry and monitoring specifications
+- **Determinism**: Reproducible agent behaviors through formal specifications
+
+## Architecture
+
+### Core Components
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         OSSA Architecture                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
+│  │   Agent      │  │  Discovery   │  │  Governance  │        │
+│  │  Registry    │◄─┤   Service    │─►│   Engine     │        │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘        │
+│         │                  │                  │                │
+│         ▼                  ▼                  ▼                │
+│  ┌──────────────────────────────────────────────────┐         │
+│  │            Message Bus (Event-Driven)            │         │
+│  └──────────────────────────────────────────────────┘         │
+│         │                  │                  │                │
+│         ▼                  ▼                  ▼                │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
+│  │   Worker     │  │ Orchestrator │  │   Monitor    │        │
+│  │   Agents     │  │   Agents     │  │   Agents     │        │
+│  └──────────────┘  └──────────────┘  └──────────────┘        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Agent Taxonomy
+
+OSSA defines six primary agent archetypes, each with distinct responsibilities and interface contracts:
+
+| Type | Responsibility | Interface Contract |
+|------|---------------|-------------------|
+| **Worker** | Task execution and data processing | Stateless, idempotent operations via REST/gRPC |
+| **Orchestrator** | Workflow coordination and resource allocation | Saga pattern implementation with compensation logic |
+| **Critic** | Quality assurance and validation | Immutable audit trails with cryptographic verification |
+| **Monitor** | System observability and alerting | OpenTelemetry-compliant metrics and traces |
+| **Governor** | Policy enforcement and compliance | OPA-based policy decision points |
+| **Judge** | Consensus and conflict resolution | Byzantine fault-tolerant consensus protocols |
+
+## Data Flow Architecture
+
+### Inter-Agent Communication Protocol
+
+```
+┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+│   Agent A   │       │   Message   │       │   Agent B   │
+│  (Producer) │       │     Bus     │       │ (Consumer)  │
+└─────┬───────┘       └──────┬──────┘       └──────┬──────┘
+      │                      │                      │
+      │ 1. Publish Event     │                      │
+      ├─────────────────────►│                      │
+      │                      │ 2. Route & Filter    │
+      │                      ├──────────────────────┤
+      │                      │                      │
+      │                      │ 3. Deliver Event     │
+      │                      ├─────────────────────►│
+      │                      │                      │
+      │                      │ 4. Acknowledge       │
+      │                      │◄─────────────────────┤
+      │ 5. Confirm           │                      │
+      │◄─────────────────────┤                      │
+      │                      │                      │
+```
+
+### Request Processing Pipeline
+
+```
+┌──────────┐    ┌───────────┐    ┌────────────┐    ┌──────────┐
+│  Client  │───►│   Auth    │───►│ Rate Limit │───►│  Router  │
+└──────────┘    └───────────┘    └────────────┘    └────┬─────┘
+                                                          │
+                 ┌────────────────────────────────────────┘
+                 │
+    ┌────────────▼────────────┐
+    │   Request Validation    │
+    │  • Schema validation    │
+    │  • Business rules       │
+    │  • Security policies    │
+    └────────────┬────────────┘
+                 │
+    ┌────────────▼────────────┐
+    │   Agent Dispatching     │
+    │  • Load balancing       │
+    │  • Circuit breaking     │
+    │  • Retry logic          │
+    └────────────┬────────────┘
+                 │
+    ┌────────────▼────────────┐
+    │   Response Assembly     │
+    │  • Data aggregation     │
+    │  • Format conversion    │
+    │  • Compression          │
+    └────────────┬────────────┘
+                 │
+                 ▼
+            Response
+```
+
+## Specification Components
+
+### OpenAPI 3.1 Specifications
+
+OSSA provides comprehensive API specifications using OpenAPI 3.1, leveraging advanced features:
+
+- **Discriminator Mappings**: Polymorphic agent type inheritance
+- **Webhooks**: Event-driven lifecycle notifications
+- **JSON Schema Draft 2020-12**: Advanced validation with conditional schemas
+- **Content Negotiation**: Multiple serialization formats (JSON, CBOR, MessagePack)
+- **Security Schemes**: OAuth 2.1, mTLS, API keys with rotation
+
+### Agent Manifest Schema
+
+Each agent is defined by a JSON Schema-compliant manifest:
+
+```json
+{
+  "$schema": "https://ossa.dev/schemas/agent-manifest/v1.0.0",
+  "apiVersion": "v1",
+  "kind": "Agent",
+  "metadata": {
+    "name": "data-processor",
+    "version": "1.0.0",
+    "type": "worker"
+  },
+  "spec": {
+    "capabilities": ["data-processing", "batch-operations"],
+    "interfaces": {
+      "rest": { "port": 8080, "path": "/api/v1" },
+      "grpc": { "port": 9090, "service": "DataProcessor" }
+    },
+    "requirements": {
+      "cpu": "2000m",
+      "memory": "4Gi",
+      "storage": "10Gi"
+    },
+    "scaling": {
+      "min": 1,
+      "max": 100,
+      "targetCPU": 70
+    }
+  }
+}
+```
+
+## Implementation Requirements
+
+### Minimum Viable Implementation
+
+Conformant OSSA implementations must provide:
+
+1. **API Compliance**: Full OpenAPI 3.1 specification implementation
+2. **Schema Validation**: JSON Schema Draft 2020-12 support
+3. **Authentication**: OAuth 2.1 with PKCE flow
+4. **Monitoring**: OpenTelemetry-compatible metrics export
+5. **Event Bus**: At least one supported transport (Kafka, RabbitMQ, NATS)
+6. **Service Discovery**: DNS-based or registry-based discovery
+7. **Health Checks**: Kubernetes-compatible liveness/readiness probes
+
+### Performance Benchmarks
+
+Reference implementation performance targets:
+
+| Metric | Requirement | Measurement |
+|--------|------------|-------------|
+| Latency (p99) | < 100ms | End-to-end request processing |
+| Throughput | > 10,000 req/s | Per agent instance |
+| Availability | > 99.95% | Monthly uptime |
+| MTTR | < 5 minutes | Automatic recovery time |
+| Scalability | Linear to 1000 nodes | Horizontal scaling efficiency |
+
+## Governance Model
+
+### Compliance Framework
+
+OSSA incorporates enterprise governance requirements:
+
+- **Audit Logging**: Immutable audit trails with tamper detection
+- **Policy Enforcement**: OPA-based policy decision points
+- **Data Residency**: Geographic constraint enforcement
+- **Encryption**: At-rest and in-transit encryption with key rotation
+- **Access Control**: RBAC with attribute-based extensions
+
+### Security Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                Security Perimeter                   │
+│                                                     │
+│  ┌──────────┐     ┌──────────┐    ┌──────────┐   │
+│  │   WAF    │────►│   mTLS   │───►│   RBAC   │   │
+│  └──────────┘     │  Gateway │    │  Engine  │   │
+│                   └──────────┘    └──────────┘   │
+│                         │                          │
+│  ┌──────────────────────┼──────────────────────┐  │
+│  │                      ▼                      │  │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐ │  │
+│  │  │  Secret  │  │  Policy  │  │  Audit   │ │  │
+│  │  │  Manager │  │  Engine  │  │  Logger  │ │  │
+│  │  └──────────┘  └──────────┘  └──────────┘ │  │
+│  │                                             │  │
+│  │            Internal Network                 │  │
+│  └─────────────────────────────────────────────┘  │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Deployment Patterns
+
+### Kubernetes-Native Deployment
+
+OSSA agents are designed for Kubernetes-native deployment:
+
+```yaml
+apiVersion: ossa.dev/v1
+kind: AgentDeployment
+metadata:
+  name: data-processor
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      agent.ossa.dev/type: worker
+  template:
+    metadata:
+      labels:
+        agent.ossa.dev/type: worker
+    spec:
+      agentRef:
+        name: data-processor
+        version: 1.0.0
+      resources:
+        limits:
+          cpu: "2"
+          memory: "4Gi"
+      autoscaling:
+        enabled: true
+        minReplicas: 3
+        maxReplicas: 100
+        metrics:
+        - type: CPU
+          target: 70
+```
+
+### Multi-Region Architecture
+
+```
+┌────────────────────────────────────────────────────┐
+│                  Global Load Balancer              │
+└─────────┬──────────────┬──────────────┬───────────┘
+          │              │              │
+    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
+    │  Region   │  │  Region   │  │  Region   │
+    │    US     │  │    EU     │  │   APAC    │
+    └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
+          │              │              │
+    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
+    │   Agent   │  │   Agent   │  │   Agent   │
+    │  Cluster  │◄─┤  Cluster  │─►│  Cluster  │
+    └───────────┘  └───────────┘  └───────────┘
+          ▲              ▲              ▲
+          └──────────────┼──────────────┘
+                         │
+                 ┌───────▼───────┐
+                 │  Global State │
+                 │   Store (CRD) │
+                 └───────────────┘
+```
+
+## Integration Specifications
+
+### Event-Driven Integration
+
+OSSA supports multiple event transport mechanisms:
+
+```
+Producer → Event Router → Consumer
+           │
+           ├─► Kafka (recommended for high throughput)
+           ├─► RabbitMQ (recommended for complex routing)
+           ├─► NATS (recommended for low latency)
+           └─► Redis Streams (recommended for simplicity)
+```
+
+### Protocol Support Matrix
+
+| Protocol | Use Case | Performance | Complexity |
+|----------|----------|-------------|------------|
+| REST/HTTP | Synchronous operations | Medium | Low |
+| gRPC | High-performance RPC | High | Medium |
+| GraphQL | Flexible queries | Medium | High |
+| WebSocket | Real-time streaming | High | Medium |
+| AMQP | Message queuing | High | High |
+
+## Universal Agent Protocol (UAP)
+
+UAP provides a unified communication framework for heterogeneous agent ecosystems, enabling seamless interaction between agents regardless of their underlying implementation or platform.
+
+### Core Protocol Stack
+
+UAP consists of four foundational protocols that work together to enable comprehensive agent interoperability:
+
+#### RASP (Resource Allocation & Scheduling Protocol)
+Manages resource distribution and task scheduling across agent clusters:
+
+```
+Agent Request → RASP Scheduler → Resource Pool → Task Assignment
+                     │                │              │
+                     ├─► Load Analysis ├─► Priority   ├─► Execution
+                     ├─► Constraint    ├─► Queueing   ├─► Monitoring
+                     └─► Optimization  └─► Balancing  └─► Feedback
+```
+
+#### ACAP (Agent Capability Advertisement Protocol)
+Enables dynamic service discovery and capability matching:
+
+```json
+{
+  "protocol": "ACAP/1.0",
+  "agentId": "worker-001",
+  "capabilities": [
+    {
+      "service": "data-processing",
+      "version": "2.1.0",
+      "endpoints": ["/api/v2/process"],
+      "sla": { "latency": "< 50ms", "availability": "99.9%" }
+    }
+  ],
+  "resources": {
+    "cpu": "available: 2.5 cores",
+    "memory": "available: 6.2GB"
+  }
+}
+```
+
+#### UADP (Universal Agent Discovery Protocol)
+Provides zero-configuration agent discovery with automatic topology mapping:
+
+```
+Registry Service ←→ Agent Mesh ←→ Discovery Beacon
+      │                 │               │
+      ├─► Health Check   ├─► Heartbeat   ├─► Announcement
+      ├─► Capability     ├─► Routing     ├─► Topology
+      └─► Status Update  └─► Load Info   └─► Metrics
+```
+
+#### CPC (Cross-Platform Communication)
+Standardizes message formats and transport mechanisms across different agent platforms:
+
+| Transport | Use Case | Reliability | Performance |
+|-----------|----------|-------------|-------------|
+| HTTP/3 | Synchronous RPC | High | Medium |
+| WebSocket | Real-time streams | Medium | High |
+| MQTT | IoT integration | Medium | Low |
+| gRPC | High-performance | High | High |
+
+### UAP CLI Commands
+
+The OSSA CLI provides comprehensive UAP management capabilities:
+
+#### Discovery Operations
+```bash
+# Discover agents in the network
+ossa discover --protocol UADP --filter "type=worker"
+
+# Register agent capabilities
+ossa register --capability "data-processing" --endpoint "/api/v1/process"
+
+# Query available services
+ossa query --service "machine-learning" --version ">= 2.0"
+```
+
+#### Resource Management
+```bash
+# Monitor resource allocation
+ossa resources --protocol RASP --view cluster
+
+# Request resource reservation
+ossa reserve --cpu "4 cores" --memory "8GB" --duration "2h"
+
+# Scale agent deployment
+ossa scale --agent-type worker --replicas 10 --zone us-west-2
+```
+
+#### Communication Setup
+```bash
+# Configure cross-platform communication
+ossa comm config --protocol CPC --transport grpc --encryption tls1.3
+
+# Test connectivity between agents
+ossa comm test --source agent-001 --target agent-002 --protocol all
+
+# Monitor message flows
+ossa comm monitor --protocol CPC --filter "error_rate > 1%"
+```
+
+#### Protocol Validation
+```bash
+# Validate UAP compliance
+ossa validate uap --spec-version 1.0 --agent-manifest ./agent.yaml
+
+# Generate UAP documentation
+ossa docs uap --output ./docs/uap-spec.md --format markdown
+
+# Benchmark protocol performance
+ossa benchmark uap --duration 5m --agents 100 --concurrent-requests 1000
+```
+
+### UAP Integration Example
+
+```typescript
+import { UAP, RASP, ACAP, UADP, CPC } from '@ossa/uap-client';
+
+// Initialize UAP stack
+const uap = new UAP({
+  agent: { id: 'worker-001', type: 'data-processor' },
+  protocols: {
+    rasp: { scheduler: 'kubernetes', priority: 'high' },
+    acap: { advertise: true, discovery: 'automatic' },
+    uadp: { beacon: true, mesh: 'cluster-local' },
+    cpc: { transport: ['grpc', 'websocket'] }
+  }
+});
+
+// Register capabilities
+await uap.acap.advertise({
+  service: 'data-processing',
+  version: '2.1.0',
+  endpoints: ['/api/v2/process'],
+  sla: { latency: 50, availability: 99.9 }
+});
+
+// Discover and connect to other agents
+const peers = await uap.uadp.discover({ type: 'orchestrator' });
+const connection = await uap.cpc.connect(peers[0], { protocol: 'grpc' });
+
+// Request resources for task execution
+const allocation = await uap.rasp.request({
+  cpu: '2 cores',
+  memory: '4GB',
+  duration: '1h'
+});
+```
+
+## Observability Framework
+
+### Metrics Collection
+
+OSSA mandates OpenTelemetry-compliant metrics:
+
+```
+Agent → OpenTelemetry Collector → Backend
+         │                         │
+         ├─► Metrics              ├─► Prometheus
+         ├─► Traces               ├─► Jaeger
+         └─► Logs                 └─► Elasticsearch
+```
+
+### Key Performance Indicators
+
+| Metric | Description | Alert Threshold |
+|--------|-------------|-----------------|
+| `agent_tasks_total` | Total tasks processed | - |
+| `agent_task_duration_seconds` | Task processing time | p99 > 1s |
+| `agent_error_rate` | Error percentage | > 1% |
+| `agent_saturation` | Resource utilization | > 80% |
+| `agent_availability` | Uptime percentage | < 99.9% |
+
+## Reference Implementation
+
+### Technology Stack
+
+The reference implementation demonstrates OSSA compliance using:
+
+- **Runtime**: Node.js 20 LTS with TypeScript 5.3
+- **Framework**: Express 4.18 with OpenAPI middleware
+- **Validation**: Ajv with JSON Schema Draft 2020-12
+- **Authentication**: Passport.js with OAuth 2.1
+- **Message Bus**: Kafka with Schema Registry
+- **Monitoring**: OpenTelemetry with Prometheus
+- **Container**: Docker with multi-stage builds
+- **Orchestration**: Kubernetes 1.28+
+
+### Performance Characteristics
+
+Benchmarked on AWS m5.large instances:
+
+- **Startup Time**: < 3 seconds
+- **Memory Footprint**: < 256 MB idle
+- **CPU Usage**: < 5% idle
+- **Network Overhead**: < 2% of payload
+- **Compression Ratio**: 70% with gzip
+
+## Adoption Guide
+
+### Enterprise Integration
+
+Organizations implementing OSSA should follow this phased approach:
+
+1. **Assessment Phase**: Evaluate existing agent infrastructure
+2. **Pilot Phase**: Implement reference agent in non-production
+3. **Migration Phase**: Gradually migrate existing agents
+4. **Scale Phase**: Deploy production workloads
+5. **Optimization Phase**: Fine-tune performance and costs
+
+### Compliance Verification
+
+OSSA provides automated compliance verification:
+
+```bash
+ossa validate --spec /path/to/implementation
+ossa certify --level basic|standard|advanced
+ossa audit --compliance SOC2|ISO27001|GDPR
+```
+
+## Contributing
+
+Contributions to the OSSA specification follow a formal RFC process:
+
+1. **Proposal**: Submit RFC with rationale and specification changes
+2. **Review**: Community review period (minimum 30 days)
+3. **Implementation**: Proof-of-concept in reference implementation
+4. **Testing**: Comprehensive test suite additions
+5. **Approval**: Technical steering committee review
+6. **Merge**: Integration into specification
+
+## License
+
+The OSSA specification is licensed under the MIT License. Implementations may use any license compatible with the specification requirements.
+
+## Repository
+
+- **Specification**: [gitlab.bluefly.io/llm/openapi-ai-agents-standard](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard)
+- **Reference Implementation**: [gitlab.bluefly.io/llm/agent_buildkit](https://gitlab.bluefly.io/llm/agent_buildkit)
+
+---
+
+**OSSA v0.1.9** - Enabling enterprise-grade AI agent interoperability through open standards.

package/dist/adk/adapters/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ADK Adapters for OSSA Framework
+ * Bridges OSSA components with ADK patterns
+ */
+import { ADKAgent } from '../agents/index.js';
+import { OrchestrationPattern } from '../orchestration/index.js';
+/**
+ * Main ADK Adapter for OSSA
+ */
+export declare class OSSAADKAdapter {
+    private agents;
+    private sessions;
+    /**
+     * Load OSSA agent and convert to ADK
+     */
+    loadAgent(agentPath: string): Promise<ADKAgent>;
+    /**
+     * Load all agents from .agents directory
+     */
+    loadAllAgents(baseDir?: string): Promise<void>;
+    /**
+     * Execute an agent with ADK patterns
+     */
+    executeAgent(agentName: string, input: any, sessionId?: string): Promise<any>;
+    /**
+     * Execute orchestration pattern
+     */
+    executeOrchestration(pattern: OrchestrationPattern, agentNames: string[], input?: any, options?: any): Promise<any>;
+    /**
+     * Get agent information
+     */
+    getAgentInfo(agentName: string): any;
+    /**
+     * List all loaded agents
+     */
+    listAgents(): any[];
+    /**
+     * Get session state
+     */
+    getSessionState(sessionId: string): any;
+    /**
+     * Clean up old sessions
+     */
+    cleanupSessions(olderThanMinutes?: number): number;
+}
+/**
+ * MCP-ADK Bridge
+ * Allows MCP servers to use ADK agents
+ */
+export declare class MCPADKBridge {
+    private adapter;
+    constructor(adapter: OSSAADKAdapter);
+    /**
+     * Create MCP tool from ADK agent
+     */
+    createMCPTool(agentName: string): any;
+    /**
+     * Create MCP orchestration tool
+     */
+    createMCPOrchestrationTool(pattern: OrchestrationPattern): any;
+}
+export declare const adkAdapter: OSSAADKAdapter;
+export declare const mcpBridge: MCPADKBridge;
+//# sourceMappingURL=index.d.ts.map

package/dist/adk/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adk/adapters/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,QAAQ,EAAmB,MAAM,oBAAoB,CAAC;AAM/D,OAAO,EAAuB,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKtF;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;OAEG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsDrD;;OAEG;IACG,aAAa,CAAC,OAAO,GAAE,MAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/D;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,GAAG,EACV,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,GAAG,CAAC;IA2Bf;;OAEG;IACG,oBAAoB,CACxB,OAAO,EAAE,oBAAoB,EAC7B,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,CAAC,EAAE,GAAG,EACX,OAAO,CAAC,EAAE,GAAG,GACZ,OAAO,CAAC,GAAG,CAAC;IAwBf;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG;IAepC;;OAEG;IACH,UAAU,IAAI,GAAG,EAAE;IAenB;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG;IASvC;;OAEG;IACH,eAAe,CAAC,gBAAgB,GAAE,MAAW,GAAG,MAAM;CAIvD;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,EAAE,cAAc;IAInC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG;IA6BrC;;OAEG;IACH,0BAA0B,CAAC,OAAO,EAAE,oBAAoB,GAAG,GAAG;CAiC/D;AAGD,eAAO,MAAM,UAAU,gBAAuB,CAAC;AAC/C,eAAO,MAAM,SAAS,cAA+B,CAAC"}