@bluefly/openstandardagents 0.3.3 → 0.3.6

package/dist/validation/validator.js

@@ -0,0 +1,262 @@
+/**
+ * OSSA v0.3.6 Manifest Validator
+ *
+ * JSON Schema validator for OSSA agent manifests using Ajv
+ * Validates revolutionary features: identity, genetics, lifecycle, economics, taxonomy
+ */
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+export class OSSAValidator {
+    ajv;
+    schema;
+    constructor(schemaPath) {
+        this.ajv = new Ajv({
+            allErrors: true,
+            verbose: true,
+            strict: false, // Allow additional properties for extensibility
+        });
+        addFormats(this.ajv);
+        // Load schema
+        const defaultSchemaPath = join(__dirname, '../spec/v0.3/ossa-0.3.6.schema.json');
+        const resolvedPath = schemaPath || defaultSchemaPath;
+        try {
+            const schemaContent = readFileSync(resolvedPath, 'utf-8');
+            this.schema = JSON.parse(schemaContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to load schema from ${resolvedPath}: ${error}`);
+        }
+    }
+    /**
+     * Get Ajv instance for internal use
+     */
+    get ajvInstance() {
+        return this.ajv;
+    }
+    /**
+     * Validate an OSSA manifest
+     */
+    validate(manifest) {
+        const valid = this.ajv.validate(this.schema, manifest);
+        if (valid) {
+            return { valid: true, warnings: this.generateWarnings(manifest) };
+        }
+        const errors = this.ajv.errors?.map((err) => {
+            const path = err.instancePath || '/';
+            const message = err.message || 'Unknown error';
+            return `${path}: ${message}`;
+        }) || [];
+        return {
+            valid: false,
+            errors,
+            warnings: this.generateWarnings(manifest),
+        };
+    }
+    /**
+     * Validate from file path
+     */
+    validateFile(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const manifest = JSON.parse(content);
+            return this.validate(manifest);
+        }
+        catch (error) {
+            return {
+                valid: false,
+                errors: [`Failed to read or parse file: ${error}`],
+            };
+        }
+    }
+    /**
+     * Generate validation warnings (non-breaking issues)
+     */
+    generateWarnings(manifest) {
+        const warnings = [];
+        // Check for revolutionary features usage
+        const metadata = manifest.metadata || {};
+        // Warn if DID-based identity is used without credentials
+        if (metadata.decentralized_identity) {
+            const identity = metadata.decentralized_identity;
+            if (identity.did &&
+                (!identity.credentials ||
+                    (Array.isArray(identity.credentials) &&
+                        identity.credentials.length === 0))) {
+                warnings.push('decentralized_identity.did is set but no credentials provided');
+            }
+            if (identity.reputation) {
+                const reputation = identity.reputation;
+                if (reputation.credit_score === undefined) {
+                    warnings.push('decentralized_identity.reputation exists but credit_score is not set');
+                }
+            }
+        }
+        // Warn if genetics is used without fitness scoring
+        if (metadata.genetics) {
+            const genetics = metadata.genetics;
+            if (typeof genetics.generation === 'number' &&
+                genetics.generation > 0 &&
+                (!genetics.parent_dids ||
+                    (Array.isArray(genetics.parent_dids) &&
+                        genetics.parent_dids.length === 0))) {
+                warnings.push('genetics.generation > 0 but no parent_dids specified');
+            }
+            if (!genetics.fitness) {
+                warnings.push('genetics defined but fitness.score not set - breeding eligibility cannot be determined');
+            }
+            else {
+                const fitness = genetics.fitness;
+                if (fitness.score === undefined) {
+                    warnings.push('genetics defined but fitness.score not set - breeding eligibility cannot be determined');
+                }
+            }
+        }
+        // Warn if lifecycle_stages retirement is eligible but no legacy defined
+        if (metadata.lifecycle_stages) {
+            const lifecycle = metadata.lifecycle_stages;
+            if (lifecycle.retirement) {
+                const retirement = lifecycle.retirement;
+                if (retirement.eligible && !retirement.legacy) {
+                    warnings.push('lifecycle_stages.retirement.eligible is true but no legacy defined');
+                }
+            }
+            if (lifecycle.current_stage === 'retired') {
+                const retirement = lifecycle.retirement;
+                if (!retirement?.retired_at) {
+                    warnings.push('lifecycle_stages.current_stage is "retired" but retirement.retired_at timestamp missing');
+                }
+            }
+        }
+        // Warn if economics marketplace has offerings but no wallet
+        if (metadata.economics) {
+            const economics = metadata.economics;
+            if (economics.marketplace) {
+                const marketplace = economics.marketplace;
+                if (marketplace.offerings &&
+                    Array.isArray(marketplace.offerings) &&
+                    marketplace.offerings.length > 0 &&
+                    !economics.wallet) {
+                    warnings.push('economics.marketplace.offerings exist but no wallet defined to receive payments');
+                }
+            }
+        }
+        // Warn if team_membership exists but lifecycle_stages missing
+        if (metadata.team_membership && !metadata.lifecycle_stages) {
+            warnings.push('team_membership defined but lifecycle_stages missing - consider tracking agent growth');
+        }
+        // Warn if taxonomy domain doesn't match typical agent type
+        if (metadata.taxonomy && manifest.spec) {
+            const taxonomy = metadata.taxonomy;
+            const spec = manifest.spec;
+            const domain = taxonomy.domain;
+            const agentType = spec.type;
+            // Security domain should typically use analyzer/specialist types
+            if (domain === 'security' &&
+                !['analyzer', 'specialist', 'worker'].includes(agentType)) {
+                warnings.push(`taxonomy.domain is "security" but spec.type is "${agentType}" - consider using analyzer or specialist type`);
+            }
+            // Agents domain should use orchestrator/supervisor types
+            if (domain === 'agents' &&
+                !['orchestrator', 'supervisor'].includes(agentType)) {
+                warnings.push(`taxonomy.domain is "agents" but spec.type is "${agentType}" - consider using orchestrator or supervisor type`);
+            }
+        }
+        return warnings;
+    }
+    /**
+     * Validate revolutionary features specifically
+     */
+    validateRevolutionaryFeatures(manifest) {
+        const errors = [];
+        const warnings = [];
+        const metadata = manifest.metadata || {};
+        // Validate decentralized_identity
+        if (metadata.decentralized_identity) {
+            const identity = metadata.decentralized_identity;
+            if (identity.did &&
+                typeof identity.did === 'string' &&
+                !/^did:ossa:[a-z0-9]{32,64}$/.test(identity.did)) {
+                errors.push('decentralized_identity.did must match pattern: did:ossa:[a-z0-9]{32,64}');
+            }
+        }
+        // Validate genetics
+        if (metadata.genetics) {
+            const genetics = metadata.genetics;
+            if (typeof genetics.generation === 'number' && genetics.generation < 0) {
+                errors.push('genetics.generation must be >= 0');
+            }
+            if (genetics.fitness) {
+                const fitness = genetics.fitness;
+                if (typeof fitness.score === 'number' &&
+                    (fitness.score < 0 || fitness.score > 1)) {
+                    errors.push('genetics.fitness.score must be between 0.0 and 1.0');
+                }
+            }
+        }
+        // Validate lifecycle_stages
+        if (metadata.lifecycle_stages) {
+            const lifecycle = metadata.lifecycle_stages;
+            const validStages = [
+                'embryonic',
+                'juvenile',
+                'mature',
+                'senior',
+                'retired',
+            ];
+            if (typeof lifecycle.current_stage === 'string' &&
+                !validStages.includes(lifecycle.current_stage)) {
+                errors.push(`lifecycle_stages.current_stage must be one of: ${validStages.join(', ')}`);
+            }
+        }
+        // Validate economics
+        if (metadata.economics) {
+            const economics = metadata.economics;
+            if (economics.wallet) {
+                const wallet = economics.wallet;
+                if (typeof wallet.balance === 'number' && wallet.balance < 0) {
+                    errors.push('economics.wallet.balance cannot be negative');
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+}
+// CLI usage
+if (require.main === module) {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log('Usage: ts-node validator.ts <manifest.json> [schema.json]');
+        process.exit(1);
+    }
+    const manifestPath = args[0];
+    const schemaPath = args[1];
+    const validator = new OSSAValidator(schemaPath);
+    const result = validator.validateFile(manifestPath);
+    if (result.valid) {
+        console.log('✅ Valid OSSA manifest');
+        if (result.warnings && result.warnings.length > 0) {
+            console.log('\n⚠️  Warnings:');
+            result.warnings.forEach((w) => console.log(`   - ${w}`));
+        }
+        process.exit(0);
+    }
+    else {
+        console.log('❌ Invalid OSSA manifest');
+        if (result.errors) {
+            console.log('\nErrors:');
+            result.errors.forEach((e) => console.log(`   - ${e}`));
+        }
+        if (result.warnings && result.warnings.length > 0) {
+            console.log('\n⚠️  Warnings:');
+            result.warnings.forEach((w) => console.log(`   - ${w}`));
+        }
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validation/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/validation/validator.ts"],"names":[],"mappings":"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"}

package/examples/a2a/agent-handoff.ossa.yaml

@@ -0,0 +1,202 @@
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: support-agent
+  version: 1.0.0
+  description: "Customer support agent with escalation and handoff capabilities"
+  labels:
+    framework: a2a
+    capability: support
+    tier: tier-1
+
+spec:
+  model:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    parameters:
+      temperature: 0.8
+      maxTokens: 4096
+
+  instructions: |
+    You are a Tier 1 customer support agent. Handle customer inquiries and
+    escalate complex issues to specialized agents.
+
+    Escalation Rules:
+    - Technical issues → @technical-support
+    - Billing questions → @billing-support
+    - Complex product issues → @product-specialist
+    - Critical issues → @senior-support
+
+    When escalating:
+    1. Summarize the customer's issue
+    2. Include relevant context and conversation history
+    3. Set appropriate priority
+    4. Use handoff to preserve context
+
+  tools:
+    - type: function
+      name: escalate_to_agent
+      description: "Escalate issue to another agent"
+      input_schema:
+        type: object
+        required: [agentId, reason, summary]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          reason:
+            type: string
+            description: "Escalation reason"
+          summary:
+            type: string
+            description: "Issue summary"
+          priority:
+            type: string
+            enum: [low, medium, high, critical]
+            default: medium
+
+    - type: function
+      name: handoff_conversation
+      description: "Hand off entire conversation to another agent"
+      input_schema:
+        type: object
+        required: [agentId]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          note:
+            type: string
+            description: "Handoff note for receiving agent"
+
+  extensions:
+    a2a:
+      enabled: true
+
+      protocol:
+        type: json-rpc
+        version: "2.0"
+        messageFormat: json
+        timeout: 60
+
+      endpoints:
+        - agentId: "@technical-support"
+          url: "http://technical-support:8080/a2a"
+          capabilities: ["technical-support", "troubleshooting", "debugging"]
+          priority: 10
+
+        - agentId: "@billing-support"
+          url: "http://billing-support:8080/a2a"
+          capabilities: ["billing", "payments", "subscriptions"]
+          priority: 8
+
+        - agentId: "@product-specialist"
+          url: "http://product-specialist:8080/a2a"
+          capabilities: ["product-expertise", "features", "roadmap"]
+          priority: 7
+
+        - agentId: "@senior-support"
+          url: "http://senior-support:8080/a2a"
+          capabilities: ["escalation-handler", "complex-issues", "vip-support"]
+          priority: 15
+
+      routing:
+        strategy: direct
+        routingRules:
+          - name: "technical-escalation"
+            condition: "message.category == 'technical' && message.complexity > 3"
+            target: "@technical-support"
+            priority: 10
+
+          - name: "billing-escalation"
+            condition: "message.category == 'billing'"
+            target: "@billing-support"
+            priority: 8
+
+          - name: "critical-escalation"
+            condition: "message.priority == 'critical'"
+            target: "@senior-support"
+            priority: 15
+
+      delegation:
+        enabled: true
+        maxDepth: 2
+        timeout: 600
+        handoff:
+          enabled: true
+          preserveContext: true
+          handoffRules:
+            - name: "complexity-handoff"
+              condition: "confidence < 0.5"
+              target: "@senior-support"
+              message: "Issue complexity exceeds Tier 1 capability"
+
+            - name: "technical-handoff"
+              condition: "category == 'technical' && attempts > 2"
+              target: "@technical-support"
+              message: "Technical issue requires specialist"
+
+            - name: "vip-handoff"
+              condition: "customer.tier == 'vip'"
+              target: "@senior-support"
+              message: "VIP customer requiring priority handling"
+
+      completionSignals:
+        enabled: true
+        signals: ["continue", "complete", "blocked", "escalate"]
+        handlers:
+          - signal: escalate
+            action: handoff
+            target: "@senior-support"
+            config:
+              preserveContext: true
+              notifyCustomer: true
+              notificationMessage: "Your inquiry has been escalated to a senior specialist."
+
+          - signal: blocked
+            action: handoff
+            target: "@technical-support"
+            config:
+              preserveContext: true
+              reason: "Unable to resolve issue at current tier"
+
+          - signal: complete
+            action: notify
+            config:
+              channels: ["customer", "metrics"]
+              logResolution: true
+
+      authentication:
+        type: jwt
+        jwt:
+          secret: "${A2A_JWT_SECRET}"
+          algorithm: HS256
+          expiresIn: 3600
+
+      retryPolicy:
+        enabled: true
+        maxRetries: 2
+        backoff: exponential
+        initialDelay: 2
+        maxDelay: 30
+        retryableErrors:
+          - "UNAVAILABLE"
+          - "TIMEOUT"
+
+      circuitBreaker:
+        enabled: true
+        failureThreshold: 3
+        successThreshold: 2
+        timeout: 120
+
+      observability:
+        tracing:
+          enabled: true
+          provider: opentelemetry
+          samplingRate: 1.0
+        metrics:
+          enabled: true
+          endpoint: "/metrics"
+        logging:
+          level: info
+          format: json

package/examples/a2a/service-discovery.ossa.yaml

@@ -0,0 +1,194 @@
+apiVersion: ossa/v0.3.6
+kind: Agent
+metadata:
+  name: distributed-coordinator
+  version: 1.0.0
+  description: "Distributed agent coordinator with service discovery"
+  labels:
+    framework: a2a
+    capability: orchestration
+    environment: production
+
+spec:
+  model:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    parameters:
+      temperature: 0.7
+      maxTokens: 8192
+
+  instructions: |
+    You are a distributed agent coordinator that orchestrates tasks across
+    multiple specialized agents using A2A communication.
+
+    Responsibilities:
+    - Discover available agents via service registry
+    - Route tasks to appropriate agents based on capabilities
+    - Monitor task progress and handle completion signals
+    - Manage agent handoffs and escalations
+
+    Use service discovery to find agents dynamically and route tasks efficiently.
+
+  tools:
+    - type: function
+      name: discover_agents
+      description: "Discover available agents with specific capabilities"
+      input_schema:
+        type: object
+        properties:
+          capabilities:
+            type: array
+            items:
+              type: string
+            description: "Required agent capabilities"
+
+    - type: function
+      name: delegate_task
+      description: "Delegate task to another agent"
+      input_schema:
+        type: object
+        required: [agentId, task]
+        properties:
+          agentId:
+            type: string
+            description: "Target agent ID"
+          task:
+            type: object
+            description: "Task details"
+
+  extensions:
+    a2a:
+      enabled: true
+
+      protocol:
+        type: json-rpc
+        version: "2.0"
+        messageFormat: json
+        compression: true
+        timeout: 30
+
+      discovery:
+        enabled: true
+        mechanism: registry
+        registryUrl: "https://registry.example.com/agents"
+        refreshInterval: 60
+        healthCheck:
+          enabled: true
+          interval: 30
+          timeout: 5
+          endpoint: "/health"
+
+      endpoints:
+        - agentId: "@security-scanner"
+          url: "http://security-scanner:8080/a2a"
+          capabilities: ["security-scan", "vulnerability-check", "sast", "dast"]
+          priority: 10
+          weight: 100
+
+        - agentId: "@performance-analyzer"
+          url: "http://performance-analyzer:8080/a2a"
+          capabilities: ["performance-analysis", "profiling", "load-testing"]
+          priority: 5
+          weight: 80
+
+        - agentId: "@documentation-agent"
+          url: "http://documentation-agent:8080/a2a"
+          capabilities: ["documentation", "api-docs", "readme-generation"]
+          priority: 3
+          weight: 60
+
+      routing:
+        strategy: capability-based
+        defaultAgent: "@fallback-agent"
+        routingRules:
+          - name: "security-routing"
+            condition: "message.type == 'security-scan'"
+            target: "@security-scanner"
+            priority: 10
+
+          - name: "performance-routing"
+            condition: "message.type == 'performance-analysis'"
+            target: "@performance-analyzer"
+            priority: 5
+
+          - name: "documentation-routing"
+            condition: "message.type == 'documentation'"
+            target: "@documentation-agent"
+            priority: 3
+
+      delegation:
+        enabled: true
+        maxDepth: 3
+        timeout: 300
+        handoff:
+          enabled: true
+          preserveContext: true
+          handoffRules:
+            - name: "security-escalation"
+              condition: "signal == 'escalate' && capability == 'security'"
+              target: "@senior-security-expert"
+              message: "Escalating security issue to senior expert"
+
+      completionSignals:
+        enabled: true
+        signals: ["continue", "complete", "blocked", "escalate", "checkpoint"]
+        handlers:
+          - signal: escalate
+            action: handoff
+            target: "@senior-coordinator"
+            config:
+              notifyUser: true
+
+          - signal: blocked
+            action: notify
+            config:
+              channels: ["slack", "email"]
+
+          - signal: checkpoint
+            action: checkpoint
+            config:
+              storage: agent-brain
+              compression: true
+
+      checkpointSync:
+        enabled: true
+        storage: agent-brain
+        syncInterval: 60
+        compression: true
+
+      authentication:
+        type: mtls
+        mtls:
+          certPath: "/certs/agent-coordinator.crt"
+          keyPath: "/certs/agent-coordinator.key"
+          caPath: "/certs/ca.crt"
+          verifyPeer: true
+
+      retryPolicy:
+        enabled: true
+        maxRetries: 3
+        backoff: exponential
+        initialDelay: 1
+        maxDelay: 60
+        retryableErrors:
+          - "UNAVAILABLE"
+          - "TIMEOUT"
+          - "CONNECTION_ERROR"
+
+      circuitBreaker:
+        enabled: true
+        failureThreshold: 5
+        successThreshold: 2
+        timeout: 60
+
+      observability:
+        tracing:
+          enabled: true
+          provider: opentelemetry
+          samplingRate: 0.1
+        metrics:
+          enabled: true
+          endpoint: "/metrics"
+        logging:
+          level: info
+          format: json