@bluefly/openstandardagents 0.2.9 → 0.3.0

package/examples/reference-implementations/typescript-client/examples/messaging.ts

@@ -0,0 +1,185 @@
+/**
+ * Agent-to-Agent Messaging Example
+ *
+ * Demonstrates A2A messaging including:
+ * - Sending messages
+ * - Registering webhooks
+ * - Event streaming
+ */
+
+import { OSSA } from '../src/index.js';
+
+async function main() {
+  const token = process.env.OSSA_TOKEN;
+  if (!token) {
+    console.error('❌ Error: OSSA_TOKEN environment variable is required');
+    process.exit(1);
+  }
+
+  const client = new OSSA({ bearerToken: token });
+
+  console.log('💬 OSSA TypeScript Client - Messaging Example\n');
+
+  try {
+    // 1. Send a simple A2A message
+    console.log('1️⃣  Sending A2A message...');
+    const messageResult = await client.messaging.sendMessage({
+      from: {
+        publisher: 'myorg',
+        name: 'my-agent',
+        version: '1.0.0',
+      },
+      to: {
+        publisher: 'blueflyio',
+        name: 'security-scanner',
+        version: '2.0.0',
+      },
+      type: 'request',
+      capability: 'vulnerability-scan',
+      payload: {
+        target: 'https://example.com',
+        scan_type: 'full',
+        options: {
+          check_ssl: true,
+          check_headers: true,
+        },
+      },
+      metadata: {
+        correlation_id: `scan-${Date.now()}`,
+        priority: 'high',
+        ttl: 300, // 5 minutes
+      },
+    });
+
+    console.log(`   ✓ Message sent: ${messageResult.message_id}`);
+    console.log(`   Status: ${messageResult.status}`);
+    console.log(`   Timestamp: ${messageResult.timestamp}\n`);
+
+    // 2. Send a synchronous request
+    console.log('2️⃣  Sending synchronous request...');
+    const requestResult = await client.messaging.sendRequest(
+      {
+        from: { publisher: 'myorg', name: 'my-agent' },
+        to: { publisher: 'blueflyio', name: 'code-analyzer' },
+        capability: 'analyze',
+        payload: {
+          code: 'function hello() { console.log("Hello"); }',
+          language: 'javascript',
+        },
+      },
+      30000 // 30 second timeout
+    );
+
+    console.log(`   Request: ${requestResult.request_id}`);
+    console.log(`   Status: ${requestResult.status}`);
+
+    if (requestResult.response) {
+      console.log('   Response received:');
+      console.log(`   ${JSON.stringify(requestResult.response.payload, null, 2)}\n`);
+    }
+
+    // 3. Broadcast a message
+    console.log('3️⃣  Broadcasting message to all security agents...');
+    const broadcastResult = await client.messaging.broadcast(
+      {
+        from: { publisher: 'myorg', name: 'my-agent' },
+        capability: 'security-alert',
+        payload: {
+          alert_type: 'vulnerability_detected',
+          severity: 'high',
+          details: {
+            cve: 'CVE-2024-1234',
+            affected_systems: ['web-server-1', 'web-server-2'],
+          },
+        },
+      },
+      {
+        domain: 'security',
+        capability: 'incident-response',
+      }
+    );
+
+    console.log(`   ✓ Broadcast sent: ${broadcastResult.broadcast_id}`);
+    console.log(`   Recipients: ${broadcastResult.recipients_count} agents\n`);
+
+    // 4. Register a webhook
+    console.log('4️⃣  Registering webhook for agent events...');
+    const webhook = await client.messaging.registerWebhook({
+      url: 'https://example.com/webhooks/ossa',
+      events: ['agent.deployed', 'agent.error', 'message.received'],
+      filters: {
+        publisher: 'blueflyio',
+      },
+      headers: {
+        'X-Webhook-Secret': 'your-secret-key',
+      },
+      retry_config: {
+        max_attempts: 3,
+        backoff_strategy: 'exponential',
+      },
+    });
+
+    console.log(`   ✓ Webhook registered: ${webhook.id}`);
+    console.log(`   URL: ${webhook.url}`);
+    console.log(`   Events: ${webhook.events.join(', ')}`);
+    console.log(`   Active: ${webhook.active}\n`);
+
+    // 5. Subscribe to events
+    console.log('5️⃣  Subscribing to agent events...');
+    const subscription = await client.messaging.subscribe({
+      agent: {
+        publisher: 'blueflyio',
+        name: 'security-scanner',
+      },
+      events: ['scan.completed', 'scan.failed'],
+      delivery_mode: 'polling',
+    });
+
+    console.log(`   ✓ Subscription created: ${subscription.subscription_id}`);
+    console.log(`   Status: ${subscription.status}\n`);
+
+    // 6. Stream events (demonstration)
+    console.log('6️⃣  Streaming events (will run for 10 seconds)...');
+    console.log('   Waiting for events...\n');
+
+    const streamTimeout = setTimeout(() => {
+      console.log('\n   ⏱️  Stream timeout - ending example');
+    }, 10000);
+
+    let eventCount = 0;
+    try {
+      for await (const event of client.messaging.streamEvents({
+        agent: { publisher: 'blueflyio', name: 'security-scanner' },
+        event_types: ['scan.completed'],
+      })) {
+        eventCount++;
+        console.log(`   📨 Event ${eventCount}: ${event.event_type}`);
+        console.log(`      Agent: ${event.agent.publisher}/${event.agent.name}`);
+        console.log(`      Timestamp: ${event.timestamp}`);
+        console.log(`      Payload: ${JSON.stringify(event.payload).substring(0, 100)}...\n`);
+
+        if (eventCount >= 5) {
+          clearTimeout(streamTimeout);
+          break;
+        }
+      }
+    } catch (error) {
+      clearTimeout(streamTimeout);
+      if (error instanceof Error && error.message.includes('timeout')) {
+        console.log('   No events received during streaming period\n');
+      } else {
+        throw error;
+      }
+    }
+
+    console.log('✅ Messaging example completed successfully!');
+  } catch (error) {
+    console.error('❌ Error:', error);
+    if (error instanceof Error) {
+      console.error('   Message:', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/examples/reference-implementations/typescript-client/examples/publish-agent.ts

@@ -0,0 +1,138 @@
+/**
+ * Agent Publishing Example
+ *
+ * Demonstrates how to publish an agent to the OSSA registry.
+ */
+
+import { OSSA, AgentManifest } from '../src/index.js';
+
+async function main() {
+  // Initialize with authentication
+  const token = process.env.OSSA_TOKEN;
+  if (!token) {
+    console.error('❌ Error: OSSA_TOKEN environment variable is required');
+    console.error('   Run: export OSSA_TOKEN=ossa_tok_xxx');
+    process.exit(1);
+  }
+
+  const client = new OSSA({ bearerToken: token });
+
+  console.log('📦 OSSA TypeScript Client - Agent Publishing Example\n');
+
+  // Define the agent manifest
+  const manifest: AgentManifest = {
+    apiVersion: 'ossa/v0.3.0',
+    kind: 'Agent',
+    metadata: {
+      name: 'example-typescript-agent',
+      version: '1.0.0',
+      description: 'Example agent published from TypeScript SDK',
+      labels: {
+        environment: 'production',
+        team: 'engineering',
+      },
+    },
+    spec: {
+      taxonomy: {
+        domain: 'development',
+        subdomain: 'code-quality',
+        capability: 'linting',
+      },
+      role: 'Code quality analysis agent that performs automated linting and style checks',
+      llm: {
+        provider: 'anthropic',
+        model: 'claude-sonnet-4',
+        temperature: 0.3,
+        maxTokens: 4000,
+      },
+      capabilities: [
+        {
+          name: 'lint_code',
+          description: 'Analyze code and provide linting recommendations',
+          input_schema: {
+            type: 'object',
+            required: ['code', 'language'],
+            properties: {
+              code: { type: 'string' },
+              language: { type: 'string' },
+              rules: { type: 'object' },
+            },
+          },
+          output_schema: {
+            type: 'object',
+            properties: {
+              issues: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    line: { type: 'number' },
+                    severity: { type: 'string' },
+                    message: { type: 'string' },
+                    rule: { type: 'string' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      ],
+      runtime: {
+        type: 'serverless',
+        config: {
+          timeout: 300,
+          memory: '512Mi',
+        },
+      },
+    },
+  };
+
+  try {
+    console.log('1️⃣  Publishing agent...');
+    console.log(`   Name: ${manifest.metadata.name}`);
+    console.log(`   Version: ${manifest.metadata.version}`);
+    console.log(`   Description: ${manifest.metadata.description}\n`);
+
+    const result = await client.agents.publish({
+      manifest,
+      package: {
+        tarball_url: 'https://example.com/agents/example-typescript-agent-1.0.0.tgz',
+        shasum: 'a'.repeat(64), // SHA-256 checksum
+        size_bytes: 1024 * 100, // 100KB
+      },
+      documentation: {
+        readme: 'https://github.com/example/example-typescript-agent#readme',
+        repository: 'https://github.com/example/example-typescript-agent',
+      },
+      license: 'Apache-2.0',
+      keywords: ['linting', 'code-quality', 'typescript'],
+    });
+
+    console.log('✅ Agent published successfully!\n');
+    console.log(`   Status: ${result.status}`);
+    console.log(`   Agent: ${result.agent.publisher}/${result.agent.name}`);
+    console.log(`   Version: ${result.agent.version}`);
+    console.log(`   Published at: ${new Date(result.agent.published_at).toISOString()}`);
+    console.log(`   Registry URL: ${result.agent.registry_url}`);
+    console.log(`   Package URL: ${result.agent.package_url}\n`);
+
+    console.log('   Verification:');
+    console.log(`   - Schema valid: ${result.verification.schema_valid ? '✓' : '✗'}`);
+    console.log(`   - Security scan: ${result.verification.security_scan}`);
+    console.log(`   - Verified publisher: ${result.verification.verified_publisher ? '✓' : '✗'}\n`);
+
+    // Wait for verification if pending
+    if (result.verification.security_scan === 'pending') {
+      console.log('⏳ Security scan is pending. Check back later for results.');
+      console.log(`   Monitor at: ${result.agent.registry_url}\n`);
+    }
+  } catch (error) {
+    console.error('❌ Publishing failed:', error);
+    if (error instanceof Error) {
+      console.error('   Message:', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/examples/reference-implementations/typescript-client/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ossa/typescript-client",
+  "version": "1.0.0",
+  "description": "TypeScript reference implementation for OSSA API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "example": "tsx examples/basic-usage.ts",
+    "example:search": "tsx examples/search-agents.ts",
+    "example:publish": "tsx examples/publish-agent.ts",
+    "example:messaging": "tsx examples/messaging.ts"
+  },
+  "keywords": [
+    "ossa",
+    "agents",
+    "ai",
+    "sdk",
+    "typescript"
+  ],
+  "author": "OSSA Community",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/examples/reference-implementations/typescript-client/src/agents.ts

@@ -0,0 +1,285 @@
+/**
+ * OSSA Agent Operations
+ *
+ * Client methods for agent discovery, publishing, and lifecycle management.
+ */
+
+import { OSSAClient } from './client.js';
+
+export interface AgentManifest {
+  apiVersion: string;
+  kind: 'Agent';
+  metadata: {
+    name: string;
+    version: string;
+    description: string;
+    labels?: Record<string, string>;
+  };
+  spec: {
+    taxonomy: {
+      domain: string;
+      subdomain?: string;
+      capability?: string;
+    };
+    role: string;
+    llm?: {
+      provider: string;
+      model: string;
+      temperature?: number;
+      maxTokens?: number;
+    };
+    capabilities?: Array<{
+      name: string;
+      description: string;
+      input_schema: Record<string, unknown>;
+      output_schema: Record<string, unknown>;
+    }>;
+    runtime?: {
+      type: string;
+      config?: Record<string, unknown>;
+    };
+  };
+}
+
+export interface PublishRequest {
+  manifest: AgentManifest;
+  package: {
+    tarball_url: string;
+    shasum: string;
+    size_bytes: number;
+  };
+  documentation?: {
+    readme?: string;
+    changelog?: string;
+    repository?: string;
+  };
+  license: string;
+  keywords?: string[];
+  dependencies?: Record<string, string>;
+}
+
+export interface PublishResponse {
+  status: 'published' | 'pending' | 'failed';
+  agent: {
+    name: string;
+    version: string;
+    publisher: string;
+    published_at: string;
+    registry_url: string;
+    package_url: string;
+  };
+  verification: {
+    schema_valid: boolean;
+    security_scan: 'passed' | 'failed' | 'pending';
+    verified_publisher: boolean;
+  };
+}
+
+export interface SearchParams {
+  q?: string;
+  tag?: string;
+  capability?: string;
+  domain?: string;
+  publisher?: string;
+  license?: string;
+  compliance?: string;
+  verified?: boolean;
+  min_rating?: number;
+  sort?: 'downloads' | 'rating' | 'updated' | 'created' | 'relevance';
+  limit?: number;
+  offset?: number;
+}
+
+export interface AgentSearchResult {
+  name: string;
+  version: string;
+  publisher: string;
+  description: string;
+  license: string;
+  downloads: number;
+  rating: number;
+  verified: boolean;
+  tags: string[];
+  capabilities: string[];
+  created_at: string;
+  updated_at: string;
+  registry_url: string;
+}
+
+export interface SearchResponse {
+  total: number;
+  limit: number;
+  offset: number;
+  agents: AgentSearchResult[];
+}
+
+export interface AgentDetails extends AgentSearchResult {
+  long_description: string;
+  repository: string;
+  homepage: string;
+  documentation: string;
+  taxonomy: {
+    domain: string;
+    subdomain?: string;
+    capability?: string;
+  };
+  compliance_profiles: string[];
+  rating_info: {
+    average: number;
+    count: number;
+  };
+  download_stats: {
+    total: number;
+    last_month: number;
+    last_week: number;
+  };
+  versions: Array<{
+    version: string;
+    published_at: string;
+    changelog?: string;
+  }>;
+  dependencies: Record<string, string>;
+  manifest_url: string;
+  package_url: string;
+}
+
+export interface VersionInfo {
+  version: string;
+  published_at: string;
+  downloads: number;
+  changelog_url?: string;
+  manifest_url: string;
+  package_url: string;
+  deprecated?: boolean;
+  deprecation_reason?: string;
+}
+
+export interface VersionsResponse {
+  agent: string;
+  versions: VersionInfo[];
+}
+
+/**
+ * Agent operations client
+ */
+export class AgentClient {
+  constructor(private client: OSSAClient) {}
+
+  /**
+   * Search and list agents
+   */
+  async search(params: SearchParams = {}): Promise<SearchResponse> {
+    return this.client.request<SearchResponse>({
+      method: 'GET',
+      path: '/agents',
+      query: params as Record<string, string | number | boolean>,
+    });
+  }
+
+  /**
+   * Publish a new agent or version
+   */
+  async publish(request: PublishRequest): Promise<PublishResponse> {
+    return this.client.request<PublishResponse>({
+      method: 'POST',
+      path: '/agents',
+      body: request,
+    });
+  }
+
+  /**
+   * Get agent details (latest version)
+   */
+  async get(publisher: string, name: string): Promise<AgentDetails> {
+    return this.client.request<AgentDetails>({
+      method: 'GET',
+      path: `/agents/${publisher}/${name}`,
+    });
+  }
+
+  /**
+   * Get specific agent version
+   */
+  async getVersion(publisher: string, name: string, version: string): Promise<AgentDetails> {
+    return this.client.request<AgentDetails>({
+      method: 'GET',
+      path: `/agents/${publisher}/${name}/${version}`,
+    });
+  }
+
+  /**
+   * List all versions of an agent
+   */
+  async listVersions(publisher: string, name: string): Promise<VersionsResponse> {
+    return this.client.request<VersionsResponse>({
+      method: 'GET',
+      path: `/agents/${publisher}/${name}/versions`,
+    });
+  }
+
+  /**
+   * Unpublish a specific agent version
+   */
+  async unpublish(
+    publisher: string,
+    name: string,
+    version: string,
+    reason?: string
+  ): Promise<{ status: string; agent: string; version: string; unpublished_at: string }> {
+    return this.client.request({
+      method: 'DELETE',
+      path: `/agents/${publisher}/${name}/${version}`,
+      body: reason ? { reason } : undefined,
+    });
+  }
+
+  /**
+   * Deprecate a specific agent version
+   */
+  async deprecate(
+    publisher: string,
+    name: string,
+    version: string,
+    reason: string,
+    replacementVersion?: string
+  ): Promise<{
+    status: string;
+    agent: string;
+    version: string;
+    deprecated_at: string;
+    replacement_version?: string;
+  }> {
+    return this.client.request({
+      method: 'POST',
+      path: `/agents/${publisher}/${name}/${version}/deprecate`,
+      body: {
+        reason,
+        replacement_version: replacementVersion,
+      },
+    });
+  }
+
+  /**
+   * Get agent dependencies
+   */
+  async getDependencies(
+    publisher: string,
+    name: string,
+    version?: string
+  ): Promise<{
+    agent: string;
+    version: string;
+    dependencies: {
+      runtime?: Record<string, unknown>;
+      agents?: Record<string, unknown>;
+      tools?: Record<string, unknown>;
+    };
+    dependency_tree: Record<string, unknown>;
+  }> {
+    return this.client.request({
+      method: 'GET',
+      path: `/agents/${publisher}/${name}/dependencies`,
+      query: version ? { version } : undefined,
+    });
+  }
+}