@bluefly/openstandardagents 0.2.9 → 0.3.0

package/schemas/communication.json

@@ -0,0 +1,897 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ossa.dev/schemas/communication/v0.3.0/communication.json",
+  "title": "OSSA Agent Communication Schemas",
+  "description": "JSON Schema definitions for OSSA v0.3.0 Agent-to-Agent Communication, including message types, channels, and subscriptions",
+  "definitions": {
+    "Message": {
+      "$id": "#/definitions/Message",
+      "type": "object",
+      "title": "Message",
+      "description": "Core message structure for agent-to-agent communication",
+      "required": [
+        "id",
+        "to",
+        "from",
+        "type",
+        "payload",
+        "status",
+        "createdAt"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique message identifier"
+        },
+        "to": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Target agent URI (e.g., agent://worker-001)",
+          "examples": ["agent://worker-001", "agent://orchestrator-main"]
+        },
+        "from": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Source agent URI",
+          "examples": ["agent://orchestrator-main", "agent://worker-002"]
+        },
+        "type": {
+          "$ref": "#/definitions/MessageType"
+        },
+        "payload": {
+          "$ref": "#/definitions/MessagePayload"
+        },
+        "correlationId": {
+          "type": "string",
+          "description": "Correlation ID for request/reply pattern"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "delivered", "acknowledged", "failed"],
+          "description": "Message delivery status"
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["low", "normal", "high", "critical"],
+          "default": "normal",
+          "description": "Message priority level"
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 300000,
+          "default": 30000,
+          "description": "Message timeout in milliseconds"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Message creation timestamp (ISO 8601)"
+        },
+        "deliveredAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Message delivery timestamp (ISO 8601)"
+        },
+        "acknowledgedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Message acknowledgment timestamp (ISO 8601)"
+        },
+        "error": {
+          "type": "string",
+          "description": "Error message if status is failed"
+        }
+      }
+    },
+    "MessageType": {
+      "$id": "#/definitions/MessageType",
+      "type": "string",
+      "title": "Message Type",
+      "description": "Standard message types for A2A communication",
+      "enum": [
+        "TaskAssigned",
+        "TaskCompleted",
+        "TaskFailed",
+        "QueryRequest",
+        "QueryResponse",
+        "AgentStarted",
+        "AgentStopped",
+        "AgentError",
+        "Custom"
+      ]
+    },
+    "MessagePayload": {
+      "$id": "#/definitions/MessagePayload",
+      "type": "object",
+      "title": "Message Payload",
+      "description": "Message payload structure varies by message type",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/TaskAssignedPayload"
+        },
+        {
+          "$ref": "#/definitions/TaskCompletedPayload"
+        },
+        {
+          "$ref": "#/definitions/TaskFailedPayload"
+        },
+        {
+          "$ref": "#/definitions/QueryRequestPayload"
+        },
+        {
+          "$ref": "#/definitions/QueryResponsePayload"
+        },
+        {
+          "$ref": "#/definitions/AgentStartedPayload"
+        },
+        {
+          "$ref": "#/definitions/AgentStoppedPayload"
+        },
+        {
+          "$ref": "#/definitions/AgentErrorPayload"
+        },
+        {
+          "type": "object",
+          "description": "Custom payload for application-specific messages",
+          "additionalProperties": true
+        }
+      ]
+    },
+    "TaskAssignedPayload": {
+      "$id": "#/definitions/TaskAssignedPayload",
+      "type": "object",
+      "title": "Task Assigned Payload",
+      "description": "Payload for assigning a task to an agent",
+      "required": ["taskId", "action", "input"],
+      "properties": {
+        "taskId": {
+          "type": "string",
+          "description": "Unique task identifier"
+        },
+        "action": {
+          "type": "string",
+          "description": "Action to perform (e.g., analyze_document, extract_entities)",
+          "examples": [
+            "analyze_document",
+            "extract_entities",
+            "translate_text",
+            "summarize_content"
+          ]
+        },
+        "input": {
+          "type": "object",
+          "description": "Task input parameters",
+          "additionalProperties": true,
+          "examples": [
+            {
+              "documentUrl": "https://example.com/doc.pdf",
+              "format": "pdf"
+            },
+            {
+              "text": "Sample text to analyze",
+              "language": "en"
+            }
+          ]
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["low", "normal", "high", "critical"],
+          "default": "normal",
+          "description": "Task priority"
+        },
+        "deadline": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Task deadline (ISO 8601)"
+        },
+        "context": {
+          "type": "object",
+          "description": "Additional context for task execution",
+          "additionalProperties": true
+        },
+        "retryPolicy": {
+          "$ref": "#/definitions/RetryPolicy"
+        }
+      }
+    },
+    "TaskCompletedPayload": {
+      "$id": "#/definitions/TaskCompletedPayload",
+      "type": "object",
+      "title": "Task Completed Payload",
+      "description": "Payload for task completion notification",
+      "required": ["taskId", "status", "result", "completedAt"],
+      "properties": {
+        "taskId": {
+          "type": "string",
+          "description": "Task identifier (matches TaskAssigned.taskId)"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["completed", "partial"],
+          "description": "Completion status"
+        },
+        "result": {
+          "type": "object",
+          "description": "Task execution result",
+          "additionalProperties": true,
+          "examples": [
+            {
+              "summary": "Document analyzed successfully",
+              "entities": ["Apple Inc.", "Cupertino", "California"],
+              "sentiment": "positive"
+            }
+          ]
+        },
+        "metrics": {
+          "type": "object",
+          "description": "Execution metrics",
+          "properties": {
+            "executionTimeMs": {
+              "type": "integer",
+              "description": "Execution time in milliseconds"
+            },
+            "tokensUsed": {
+              "type": "integer",
+              "description": "LLM tokens consumed"
+            },
+            "cost": {
+              "type": "number",
+              "description": "Execution cost in USD"
+            }
+          }
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Task completion timestamp (ISO 8601)"
+        },
+        "artifacts": {
+          "type": "array",
+          "description": "Output artifacts (files, URLs)",
+          "items": {
+            "type": "object",
+            "required": ["type", "url"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["file", "url", "data"],
+                "description": "Artifact type"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Artifact location"
+              },
+              "mimeType": {
+                "type": "string",
+                "description": "MIME type"
+              },
+              "sizeBytes": {
+                "type": "integer",
+                "description": "Size in bytes"
+              }
+            }
+          }
+        }
+      }
+    },
+    "TaskFailedPayload": {
+      "$id": "#/definitions/TaskFailedPayload",
+      "type": "object",
+      "title": "Task Failed Payload",
+      "description": "Payload for task failure notification",
+      "required": ["taskId", "error", "failedAt"],
+      "properties": {
+        "taskId": {
+          "type": "string",
+          "description": "Task identifier (matches TaskAssigned.taskId)"
+        },
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "Error code",
+              "examples": [
+                "TIMEOUT",
+                "INVALID_INPUT",
+                "RESOURCE_UNAVAILABLE",
+                "INTERNAL_ERROR"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "Human-readable error message"
+            },
+            "details": {
+              "type": "object",
+              "description": "Additional error details",
+              "additionalProperties": true
+            },
+            "retryable": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether the error is retryable"
+            }
+          }
+        },
+        "failedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Failure timestamp (ISO 8601)"
+        },
+        "retryCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of retry attempts made"
+        }
+      }
+    },
+    "QueryRequestPayload": {
+      "$id": "#/definitions/QueryRequestPayload",
+      "type": "object",
+      "title": "Query Request Payload",
+      "description": "Payload for querying another agent",
+      "required": ["query"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "Query text or command",
+          "examples": [
+            "Extract entities from text",
+            "Translate to Spanish",
+            "Summarize document"
+          ]
+        },
+        "context": {
+          "type": "object",
+          "description": "Query context and parameters",
+          "additionalProperties": true,
+          "examples": [
+            {
+              "text": "Apple Inc. is headquartered in Cupertino, California.",
+              "language": "en"
+            }
+          ]
+        },
+        "responseFormat": {
+          "type": "string",
+          "enum": ["json", "text", "markdown", "xml"],
+          "default": "json",
+          "description": "Desired response format"
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum tokens in response"
+        }
+      }
+    },
+    "QueryResponsePayload": {
+      "$id": "#/definitions/QueryResponsePayload",
+      "type": "object",
+      "title": "Query Response Payload",
+      "description": "Payload for query response",
+      "required": ["queryId", "response"],
+      "properties": {
+        "queryId": {
+          "type": "string",
+          "description": "Query identifier (from QueryRequest correlationId)"
+        },
+        "response": {
+          "description": "Query response data",
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Structured JSON response"
+            },
+            {
+              "type": "string",
+              "description": "Text response"
+            }
+          ]
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Confidence score (0-1)"
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Response metadata",
+          "properties": {
+            "model": {
+              "type": "string",
+              "description": "Model used for response"
+            },
+            "tokensUsed": {
+              "type": "integer",
+              "description": "Tokens consumed"
+            },
+            "latencyMs": {
+              "type": "integer",
+              "description": "Response latency in milliseconds"
+            }
+          }
+        }
+      }
+    },
+    "AgentStartedPayload": {
+      "$id": "#/definitions/AgentStartedPayload",
+      "type": "object",
+      "title": "Agent Started Payload",
+      "description": "Payload for agent startup notification",
+      "required": ["agentId", "version", "startedAt"],
+      "properties": {
+        "agentId": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Agent URI"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+)?$",
+          "description": "Agent version (semver)",
+          "examples": ["1.2.0", "2.0.0-beta.1"]
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Agent capabilities",
+          "examples": [
+            ["text_analysis", "entity_extraction", "sentiment_analysis"]
+          ]
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Startup timestamp (ISO 8601)"
+        },
+        "environment": {
+          "type": "object",
+          "description": "Runtime environment info",
+          "properties": {
+            "runtime": {
+              "type": "string",
+              "description": "Runtime environment",
+              "examples": ["nodejs-20", "python-3.11", "docker"]
+            },
+            "region": {
+              "type": "string",
+              "description": "Deployment region"
+            },
+            "zone": {
+              "type": "string",
+              "description": "Availability zone"
+            }
+          }
+        }
+      }
+    },
+    "AgentStoppedPayload": {
+      "$id": "#/definitions/AgentStoppedPayload",
+      "type": "object",
+      "title": "Agent Stopped Payload",
+      "description": "Payload for agent shutdown notification",
+      "required": ["agentId", "reason", "stoppedAt"],
+      "properties": {
+        "agentId": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Agent URI"
+        },
+        "reason": {
+          "type": "string",
+          "enum": ["shutdown", "upgrade", "error", "maintenance"],
+          "description": "Shutdown reason"
+        },
+        "message": {
+          "type": "string",
+          "description": "Additional shutdown message"
+        },
+        "stoppedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Shutdown timestamp (ISO 8601)"
+        },
+        "graceful": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether shutdown was graceful"
+        }
+      }
+    },
+    "AgentErrorPayload": {
+      "$id": "#/definitions/AgentErrorPayload",
+      "type": "object",
+      "title": "Agent Error Payload",
+      "description": "Payload for agent error notification",
+      "required": ["agentId", "error", "timestamp"],
+      "properties": {
+        "agentId": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Agent URI"
+        },
+        "error": {
+          "type": "object",
+          "required": ["code", "message", "severity"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "Error code"
+            },
+            "message": {
+              "type": "string",
+              "description": "Error message"
+            },
+            "severity": {
+              "type": "string",
+              "enum": ["info", "warning", "error", "critical"],
+              "description": "Error severity"
+            },
+            "stackTrace": {
+              "type": "string",
+              "description": "Stack trace (if available)"
+            }
+          }
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Error timestamp (ISO 8601)"
+        },
+        "context": {
+          "type": "object",
+          "description": "Error context",
+          "additionalProperties": true
+        }
+      }
+    },
+    "RetryPolicy": {
+      "$id": "#/definitions/RetryPolicy",
+      "type": "object",
+      "title": "Retry Policy",
+      "description": "Retry policy for task execution",
+      "properties": {
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 3,
+          "description": "Maximum number of retry attempts"
+        },
+        "backoffType": {
+          "type": "string",
+          "enum": ["fixed", "exponential", "linear"],
+          "default": "exponential",
+          "description": "Backoff strategy"
+        },
+        "initialDelayMs": {
+          "type": "integer",
+          "minimum": 100,
+          "default": 1000,
+          "description": "Initial retry delay in milliseconds"
+        },
+        "maxDelayMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "default": 60000,
+          "description": "Maximum retry delay in milliseconds"
+        },
+        "retryableErrors": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of retryable error codes",
+          "examples": [["TIMEOUT", "RESOURCE_UNAVAILABLE", "RATE_LIMIT"]]
+        }
+      }
+    },
+    "Channel": {
+      "$id": "#/definitions/Channel",
+      "type": "object",
+      "title": "Channel",
+      "description": "Pub/sub communication channel",
+      "required": ["id", "name", "topic", "createdAt"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique channel identifier"
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Channel name (lowercase, hyphen-separated)",
+          "examples": ["task-updates", "agent-events", "system-metrics"]
+        },
+        "topic": {
+          "type": "string",
+          "description": "Topic pattern (supports wildcards)",
+          "examples": [
+            "tasks.status.updates",
+            "agents.lifecycle.*",
+            "metrics.system.cpu"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "Channel description"
+        },
+        "subscriberCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of active subscribers"
+        },
+        "messageCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Total messages published"
+        },
+        "retentionPolicy": {
+          "$ref": "#/definitions/RetentionPolicy"
+        },
+        "accessControl": {
+          "$ref": "#/definitions/AccessControl"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Channel creation timestamp (ISO 8601)"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last update timestamp (ISO 8601)"
+        }
+      }
+    },
+    "RetentionPolicy": {
+      "$id": "#/definitions/RetentionPolicy",
+      "type": "object",
+      "title": "Retention Policy",
+      "description": "Message retention policy for channels",
+      "properties": {
+        "retentionDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 365,
+          "default": 7,
+          "description": "Number of days to retain messages"
+        },
+        "maxMessages": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 1000000,
+          "default": 10000,
+          "description": "Maximum number of messages to retain"
+        }
+      }
+    },
+    "AccessControl": {
+      "$id": "#/definitions/AccessControl",
+      "type": "object",
+      "title": "Access Control",
+      "description": "Channel access control settings",
+      "properties": {
+        "public": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether channel is publicly accessible"
+        },
+        "allowedAgents": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri",
+            "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+          },
+          "description": "List of agent URIs allowed to access channel",
+          "examples": [
+            ["agent://worker-001", "agent://worker-002", "agent://orchestrator-main"]
+          ]
+        },
+        "allowedRoles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "List of roles allowed to access channel",
+          "examples": [["worker", "orchestrator", "monitor"]]
+        }
+      }
+    },
+    "Subscription": {
+      "$id": "#/definitions/Subscription",
+      "type": "object",
+      "title": "Subscription",
+      "description": "Channel subscription",
+      "required": ["id", "channelId", "agentId", "deliveryMode", "createdAt"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique subscription identifier"
+        },
+        "channelId": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Channel identifier"
+        },
+        "agentId": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Subscribing agent URI"
+        },
+        "deliveryMode": {
+          "type": "string",
+          "enum": ["push", "pull"],
+          "description": "Message delivery mode (push=webhook, pull=polling)"
+        },
+        "webhookUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Webhook URL (required if deliveryMode=push)"
+        },
+        "filter": {
+          "$ref": "#/definitions/SubscriptionFilter"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "paused", "failed"],
+          "default": "active",
+          "description": "Subscription status"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Subscription creation timestamp (ISO 8601)"
+        },
+        "lastDeliveryAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Last message delivery timestamp (ISO 8601)"
+        },
+        "deliveryStats": {
+          "type": "object",
+          "description": "Delivery statistics",
+          "properties": {
+            "totalDelivered": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total messages delivered"
+            },
+            "totalFailed": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Total delivery failures"
+            },
+            "successRate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Delivery success rate (0-1)"
+            }
+          }
+        }
+      }
+    },
+    "SubscriptionFilter": {
+      "$id": "#/definitions/SubscriptionFilter",
+      "type": "object",
+      "title": "Subscription Filter",
+      "description": "Message filtering for subscriptions",
+      "properties": {
+        "messageTypes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/MessageType"
+          },
+          "description": "Filter by message types",
+          "examples": [
+            ["TaskAssigned", "TaskCompleted"],
+            ["AgentStarted", "AgentStopped", "AgentError"]
+          ]
+        },
+        "agentFilter": {
+          "type": "string",
+          "description": "Filter by source agent pattern (supports wildcards)",
+          "examples": ["agent://worker-*", "agent://orchestrator-*"]
+        },
+        "priorityFilter": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["low", "normal", "high", "critical"]
+          },
+          "description": "Filter by message priority",
+          "examples": [["high", "critical"]]
+        },
+        "attributeFilters": {
+          "type": "object",
+          "description": "Custom attribute filters",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "examples": [
+            {
+              "environment": "production",
+              "region": "us-east-1"
+            }
+          ]
+        }
+      }
+    },
+    "MessagePayloadWrapper": {
+      "$id": "#/definitions/MessagePayloadWrapper",
+      "type": "object",
+      "title": "Message Payload Wrapper",
+      "description": "Generic wrapper for message payloads with metadata",
+      "required": ["data", "timestamp"],
+      "properties": {
+        "data": {
+          "$ref": "#/definitions/MessagePayload"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Payload creation timestamp (ISO 8601)"
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Payload metadata",
+          "properties": {
+            "schemaVersion": {
+              "type": "string",
+              "description": "Payload schema version",
+              "examples": ["1.0.0", "2.1.0"]
+            },
+            "encoding": {
+              "type": "string",
+              "enum": ["json", "protobuf", "msgpack"],
+              "default": "json",
+              "description": "Payload encoding"
+            },
+            "compressed": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether payload is compressed"
+            },
+            "checksum": {
+              "type": "string",
+              "description": "Payload checksum (for integrity verification)"
+            }
+          }
+        }
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "$ref": "#/definitions/Message"
+    },
+    {
+      "$ref": "#/definitions/Channel"
+    },
+    {
+      "$ref": "#/definitions/Subscription"
+    },
+    {
+      "$ref": "#/definitions/MessagePayload"
+    }
+  ]
+}