@bluefly/openstandardagents 0.2.8 → 0.3.0

package/examples/contracts/data-producer-v2.ossa.yaml

@@ -0,0 +1,227 @@
+# Contract Testing Example: Data Producer v2 (Breaking Changes)
+# This is version 2.0.0 of the data-producer agent with intentional breaking changes
+# to demonstrate breaking change detection.
+#
+# Breaking Changes from v1.0.0:
+# 1. Removed "data.deleted" event (MAJOR)
+# 2. Changed "data.created" schema - made "payload.type" required (MAJOR)
+# 3. Removed "delete.data" command (MAJOR)
+# 4. Changed output schema for "create.data" command (MINOR)
+#
+# Use this to test:
+#   ossa contract breaking-changes examples/contracts/data-producer.ossa.yaml examples/contracts/data-producer-v2.ossa.yaml
+
+apiVersion: ossa/v0.3.0
+kind: Agent
+metadata:
+  name: data-producer
+  version: 2.0.0  # Major version bump due to breaking changes
+  description: Example agent v2 with breaking changes for contract testing
+  labels:
+    team: platform
+    environment: development
+    example: contract-testing-breaking-changes
+
+spec:
+  role: Data producer v2 with breaking changes
+
+  messaging:
+    # CHANGE: "data.deleted" event removed (BREAKING)
+    publishes:
+      - channel: data.created
+        description: Emitted when new data is created
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+            timestamp:
+              type: string
+              format: date-time
+            payload:
+              type: object
+              properties:
+                type:
+                  type: string
+                  enum: [user, order, product]
+                value:
+                  type: string
+              # BREAKING: Made "type" required where it wasn't before
+              required: [type, value]
+          required: [id, timestamp, payload]
+        examples:
+          - id: "data-456"
+            timestamp: "2025-12-13T10:00:00Z"
+            payload:
+              type: user
+              value: "jane.doe@example.com"
+
+      - channel: data.updated
+        description: Emitted when existing data is updated
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+            timestamp:
+              type: string
+              format: date-time
+            changes:
+              type: array
+              items:
+                type: object
+                properties:
+                  field:
+                    type: string
+                  oldValue:
+                    type: string
+                  newValue:
+                    type: string
+            # NEW: Added version field (non-breaking, optional)
+            version:
+              type: integer
+              description: Version number after update
+          required: [id, timestamp, changes]
+
+      # NEW: Added new event (non-breaking addition)
+      - channel: data.validated
+        description: Emitted when data passes validation
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+            timestamp:
+              type: string
+              format: date-time
+            validationResults:
+              type: object
+          required: [id, timestamp, validationResults]
+
+    # CHANGE: "delete.data" command removed (BREAKING)
+    commands:
+      - name: create.data
+        description: Create new data entry
+        inputSchema:
+          type: object
+          properties:
+            type:
+              type: string
+              enum: [user, order, product]
+            value:
+              type: string
+          required: [type, value]
+        outputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+            success:
+              type: boolean
+            # CHANGE: Removed "message" field from output (MINOR)
+            # Added new fields (non-breaking addition)
+            createdAt:
+              type: string
+              format: date-time
+            version:
+              type: integer
+          required: [id, success, createdAt]
+        timeoutSeconds: 30
+        idempotent: true
+        async: false
+
+      - name: update.data
+        description: Update existing data entry
+        inputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+            changes:
+              type: object
+          required: [id, changes]
+        outputSchema:
+          type: object
+          properties:
+            success:
+              type: boolean
+            message:
+              type: string
+          required: [success]
+        timeoutSeconds: 30
+        idempotent: true
+        async: false
+
+      # NEW: Added new command (non-breaking addition)
+      - name: validate.data
+        description: Validate data entry
+        inputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+          required: [id]
+        outputSchema:
+          type: object
+          properties:
+            valid:
+              type: boolean
+            errors:
+              type: array
+              items:
+                type: string
+          required: [valid]
+        timeoutSeconds: 15
+        idempotent: true
+        async: false
+
+    reliability:
+      deliveryGuarantee: at-least-once
+      retry:
+        maxAttempts: 3
+        backoffMs: 1000
+        maxBackoffMs: 10000
+      ordering:
+        enabled: true
+        key: id
+
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+      endpoint: http://jaeger:4318
+    metrics:
+      enabled: true
+      exporter: prometheus
+      endpoint: http://prometheus:9090
+    logging:
+      level: info
+      format: json
+
+# Breaking Changes Detection:
+#
+# Run:
+#   ossa contract breaking-changes examples/contracts/data-producer.ossa.yaml examples/contracts/data-producer-v2.ossa.yaml
+#
+# Expected Output:
+# MAJOR BREAKING CHANGES:
+# - removed_event: Event "data.deleted" was removed
+# - removed_command: Command "delete.data" was removed
+# - schema_incompatible: Schema for event "data.created" requires new field "payload.type"
+#
+# MINOR CHANGES:
+# - signature_changed: Output schema for command "create.data" changed (removed "message" field)
+#
+# SAFE ADDITIONS (Non-Breaking):
+# - Added event "data.validated"
+# - Added command "validate.data"
+# - Added optional field "version" to "data.updated" event
+#
+# Impact Analysis:
+# - Any consumer expecting "data.deleted" events will break
+# - Any consumer calling "delete.data" command will break
+# - Any consumer not providing "payload.type" in schema validation will break
+# - Consumers relying on "message" field in create.data output should be updated

package/examples/contracts/data-producer.ossa.yaml

@@ -0,0 +1,217 @@
+# Contract Testing Example: Data Producer Agent
+# This agent demonstrates contract testing capabilities by publishing events
+# and exposing commands that other agents can depend on.
+#
+# Contract Testing Use Cases:
+# 1. Validate that agent publishes declared events
+# 2. Validate that agent exposes declared commands
+# 3. Test schema compatibility with consumer agents
+# 4. Detect breaking changes between versions
+
+apiVersion: ossa/v0.3.0
+kind: Agent
+metadata:
+  name: data-producer
+  version: 1.0.0
+  description: Example agent that produces data events for contract testing
+  labels:
+    team: platform
+    environment: development
+    example: contract-testing
+
+spec:
+  role: Data producer that generates and publishes data events
+
+  # Messaging contract definition
+  messaging:
+    # Events published by this agent
+    publishes:
+      - channel: data.created
+        description: Emitted when new data is created
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+              description: Unique identifier for the data
+            timestamp:
+              type: string
+              format: date-time
+              description: When the data was created
+            payload:
+              type: object
+              description: The data payload
+              properties:
+                type:
+                  type: string
+                  enum: [user, order, product]
+                value:
+                  type: string
+          required: [id, timestamp, payload]
+        examples:
+          - id: "data-123"
+            timestamp: "2025-12-13T10:00:00Z"
+            payload:
+              type: user
+              value: "john.doe@example.com"
+
+      - channel: data.updated
+        description: Emitted when existing data is updated
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+            timestamp:
+              type: string
+              format: date-time
+            changes:
+              type: array
+              items:
+                type: object
+                properties:
+                  field:
+                    type: string
+                  oldValue:
+                    type: string
+                  newValue:
+                    type: string
+          required: [id, timestamp, changes]
+        examples:
+          - id: "data-123"
+            timestamp: "2025-12-13T11:00:00Z"
+            changes:
+              - field: email
+                oldValue: "old@example.com"
+                newValue: "new@example.com"
+
+      - channel: data.deleted
+        description: Emitted when data is deleted
+        contentType: application/json
+        schema:
+          type: object
+          properties:
+            id:
+              type: string
+            timestamp:
+              type: string
+              format: date-time
+            reason:
+              type: string
+          required: [id, timestamp]
+        examples:
+          - id: "data-123"
+            timestamp: "2025-12-13T12:00:00Z"
+            reason: "User requested deletion"
+
+    # Commands exposed by this agent
+    commands:
+      - name: create.data
+        description: Create new data entry
+        inputSchema:
+          type: object
+          properties:
+            type:
+              type: string
+              enum: [user, order, product]
+            value:
+              type: string
+          required: [type, value]
+        outputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+            success:
+              type: boolean
+            message:
+              type: string
+          required: [id, success]
+        timeoutSeconds: 30
+        idempotent: true
+        async: false
+
+      - name: update.data
+        description: Update existing data entry
+        inputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+            changes:
+              type: object
+          required: [id, changes]
+        outputSchema:
+          type: object
+          properties:
+            success:
+              type: boolean
+            message:
+              type: string
+          required: [success]
+        timeoutSeconds: 30
+        idempotent: true
+        async: false
+
+      - name: delete.data
+        description: Delete data entry
+        inputSchema:
+          type: object
+          properties:
+            id:
+              type: string
+            reason:
+              type: string
+          required: [id]
+        outputSchema:
+          type: object
+          properties:
+            success:
+              type: boolean
+            message:
+              type: string
+          required: [success]
+        timeoutSeconds: 30
+        idempotent: true
+        async: false
+
+    # Reliability configuration
+    reliability:
+      deliveryGuarantee: at-least-once
+      retry:
+        maxAttempts: 3
+        backoffMs: 1000
+        maxBackoffMs: 10000
+      ordering:
+        enabled: true
+        key: id
+
+  # Observability
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+      endpoint: http://jaeger:4318
+    metrics:
+      enabled: true
+      exporter: prometheus
+      endpoint: http://prometheus:9090
+    logging:
+      level: info
+      format: json
+
+# Contract Testing Commands:
+#
+# 1. Validate this agent's contract:
+#    ossa contract validate "examples/contracts/*.ossa.yaml"
+#
+# 2. Extract contract from this agent:
+#    ossa contract extract examples/contracts/data-producer.ossa.yaml
+#
+# 3. Test contract with consumer:
+#    ossa contract test examples/contracts/data-consumer.ossa.yaml examples/contracts/data-producer.ossa.yaml
+#
+# 4. Detect breaking changes between versions:
+#    ossa contract breaking-changes examples/contracts/data-producer-v1.ossa.yaml examples/contracts/data-producer-v2.ossa.yaml

package/examples/coordinator-agent/README.md

@@ -0,0 +1,180 @@
+# Coordinator Agent Reference Implementation
+
+This example demonstrates a multi-agent coordinator using the `@ossa/runtime` SDK.
+
+## Overview
+
+The coordinator agent orchestrates complex tasks by delegating work to specialized agents. It demonstrates:
+
+- Multi-agent system architecture
+- Task routing and delegation
+- Parallel task execution
+- Agent registry and discovery
+- Load balancing and availability tracking
+
+## Capabilities
+
+### 1. `delegate_task`
+Delegate a task to the most appropriate specialized agent.
+
+**Input:**
+```json
+{
+  "taskType": "process",
+  "input": { "items": [1, 2, 3] },
+  "preferredAgent": "data-processor"
+}
+```
+
+**Output:**
+```json
+{
+  "agentId": "data-processor",
+  "taskType": "process",
+  "success": true,
+  "result": { "processed": true, "items": 3 },
+  "executionTime": 150
+}
+```
+
+### 2. `delegate_parallel`
+Delegate multiple tasks to different agents in parallel.
+
+**Input:**
+```json
+{
+  "tasks": [
+    { "taskType": "process", "input": {...} },
+    { "taskType": "analyze", "input": {...} },
+    { "taskType": "notify", "input": {...} }
+  ]
+}
+```
+
+**Output:**
+```json
+{
+  "results": [
+    { "agentId": "data-processor", "success": true, ... },
+    { "agentId": "analytics-engine", "success": true, ... },
+    { "agentId": "notification-service", "success": true, ... }
+  ]
+}
+```
+
+### 3. `get_stats`
+Get coordinator statistics and health information.
+
+**Output:**
+```json
+{
+  "totalAgents": 3,
+  "availableAgents": 3,
+  "busyAgents": 0,
+  "capabilities": ["process", "analyze", "notify"]
+}
+```
+
+### 4. `list_agents`
+List all registered agents and their capabilities.
+
+**Output:**
+```json
+{
+  "agents": [
+    {
+      "id": "data-processor",
+      "role": "Process and analyze data",
+      "capabilities": ["process"],
+      "status": "available"
+    }
+  ]
+}
+```
+
+## Architecture
+
+```
+Coordinator Agent
+├── Agent Registry
+│   ├── Data Processor Agent
+│   ├── Analytics Agent
+│   └── Notification Agent
+├── Task Router (find best agent)
+├── Load Balancer (availability tracking)
+└── Execution Manager (parallel/sequential)
+```
+
+## Task Routing
+
+The coordinator uses intelligent routing:
+
+1. **Capability matching**: Find agents with required capability
+2. **Availability check**: Only route to available agents
+3. **Preferred agent**: Honor agent preferences if specified
+4. **Load balancing**: Track agent status (available/busy)
+
+## Example Flow
+
+```typescript
+import { createCoordinatorAgent } from './index.js';
+
+// Create coordinator
+const coordinator = await createCoordinatorAgent();
+
+// Register specialized agents
+coordinator.registerAgent(dataAgent, ['process', 'transform']);
+coordinator.registerAgent(analyticsAgent, ['analyze', 'report']);
+
+// Delegate complex task
+const result = await coordinator.execute('delegate_parallel', {
+  tasks: [
+    { taskType: 'process', input: { data: [...] } },
+    { taskType: 'analyze', input: { dataset: 'sales' } }
+  ]
+});
+```
+
+## Running the Example
+
+```bash
+cd examples/coordinator-agent
+npm install
+npm run build
+node dist/index.js
+```
+
+## Production Considerations
+
+This is a reference implementation. For production use:
+
+1. **Service discovery** for dynamic agent registration
+2. **Health checks** and automatic failover
+3. **Circuit breakers** for failing agents
+4. **Advanced routing** (priority, affinity, resource-based)
+5. **Queue management** for overloaded agents
+6. **Distributed coordination** across multiple machines
+7. **Metrics and monitoring** for agent performance
+8. **Agent lifecycle management** (start, stop, restart)
+9. **Security** (authentication, authorization between agents)
+10. **Message bus** for async communication (NATS, RabbitMQ)
+
+## Multi-Agent Patterns
+
+### 1. Delegation Pattern
+Coordinator delegates tasks to specialized agents.
+
+### 2. Pipeline Pattern
+Chain agents together in sequence (output → input).
+
+### 3. Fan-out/Fan-in Pattern
+Parallel execution with result aggregation.
+
+### 4. Supervisor Pattern
+Monitor agent health and restart on failure.
+
+## Related Examples
+
+- **RAG Agent**: Specialized agent for document search
+- **Workflow Agent**: Orchestrate multi-step processes
+- **Coordinator Agent**: Multi-agent task delegation (this example)