@bluefly/openstandardagents 0.3.0 → 0.3.1

package/spec/v0.3.1/schemas/messaging/channel.schema.json

@@ -0,0 +1,245 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.1/messaging/channel.json",
+  "title": "OSSA Channel Schema",
+  "description": "Schema for message channel configuration in OSSA v0.3.1",
+  "type": "object",
+  "required": [
+    "name",
+    "type"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Channel name (must follow naming conventions)",
+      "pattern": "^agents\\.([a-z0-9-]+\\.)+[a-z0-9-]+$",
+      "minLength": 3,
+      "maxLength": 256,
+      "examples": [
+        "agents.tasks.assigned",
+        "agents.code-reviewer.completed",
+        "agents.broadcast.shutdown"
+      ]
+    },
+    "type": {
+      "type": "string",
+      "enum": ["direct", "topic", "broadcast"],
+      "description": "Channel type determining routing behavior"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable channel description",
+      "maxLength": 512
+    },
+    "schema": {
+      "type": "string",
+      "description": "JSON Schema reference for message validation",
+      "format": "uri-reference",
+      "examples": [
+        "TaskAssigned",
+        "https://ossa.dev/schemas/messaging/TaskCompleted.schema.json"
+      ]
+    },
+    "qos": {
+      "$ref": "#/definitions/ChannelQoS",
+      "description": "Default quality of service for this channel"
+    },
+    "config": {
+      "$ref": "#/definitions/ChannelConfig",
+      "description": "Channel-specific configuration"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Custom metadata for channel management",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "ChannelQoS": {
+      "type": "object",
+      "description": "Default quality of service settings for channel",
+      "properties": {
+        "deliveryMode": {
+          "type": "string",
+          "enum": ["at-most-once", "at-least-once", "exactly-once"],
+          "default": "at-least-once"
+        },
+        "persistent": {
+          "type": "boolean",
+          "default": true,
+          "description": "Messages persist to disk"
+        },
+        "ordered": {
+          "type": "boolean",
+          "default": true,
+          "description": "Maintain message order"
+        },
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "default": 3,
+          "description": "Maximum delivery retry attempts"
+        },
+        "retryBackoff": {
+          "type": "string",
+          "enum": ["none", "linear", "exponential"],
+          "default": "exponential",
+          "description": "Retry backoff strategy"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ChannelConfig": {
+      "type": "object",
+      "description": "Channel configuration options",
+      "properties": {
+        "maxMessageSize": {
+          "type": "integer",
+          "minimum": 1024,
+          "maximum": 10485760,
+          "default": 1048576,
+          "description": "Maximum message size in bytes (default: 1MB)"
+        },
+        "maxSubscribers": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "default": 1000,
+          "description": "Maximum concurrent subscribers"
+        },
+        "messageRetention": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2592000,
+          "default": 86400,
+          "description": "Message retention period in seconds (default: 24 hours, 0 = no retention)"
+        },
+        "deadLetterQueue": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable dead letter queue for failed messages"
+        },
+        "dlqChannel": {
+          "type": "string",
+          "description": "Custom DLQ channel name (default: {channel}.dlq)",
+          "pattern": "^agents\\.([a-z0-9-]+\\.)+[a-z0-9-]+$"
+        },
+        "rateLimiting": {
+          "type": "object",
+          "description": "Rate limiting configuration",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false
+            },
+            "maxMessagesPerSecond": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100000
+            },
+            "burstSize": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1000
+            }
+          },
+          "additionalProperties": false
+        },
+        "encryption": {
+          "type": "object",
+          "description": "Channel-level encryption settings",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false
+            },
+            "algorithm": {
+              "type": "string",
+              "enum": ["AES-256-GCM", "ChaCha20-Poly1305"],
+              "default": "AES-256-GCM"
+            },
+            "keyRef": {
+              "type": "string",
+              "description": "Reference to encryption key in secret store"
+            }
+          },
+          "required": ["enabled"],
+          "if": {
+            "properties": {
+              "enabled": { "const": true }
+            }
+          },
+          "then": {
+            "required": ["keyRef"]
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "name": "agents.tasks.assigned",
+      "type": "topic",
+      "description": "Task assignment notifications",
+      "schema": "TaskAssigned",
+      "qos": {
+        "deliveryMode": "at-least-once",
+        "persistent": true,
+        "ordered": true,
+        "maxRetries": 5,
+        "retryBackoff": "exponential"
+      },
+      "config": {
+        "maxMessageSize": 1048576,
+        "maxSubscribers": 100,
+        "messageRetention": 86400,
+        "deadLetterQueue": true,
+        "rateLimiting": {
+          "enabled": true,
+          "maxMessagesPerSecond": 1000,
+          "burstSize": 100
+        }
+      }
+    },
+    {
+      "name": "agents.code-reviewer.tasks",
+      "type": "direct",
+      "description": "Direct task assignments to code-reviewer agent",
+      "schema": "ReviewTask",
+      "qos": {
+        "deliveryMode": "exactly-once",
+        "persistent": true,
+        "ordered": true
+      },
+      "config": {
+        "maxMessageSize": 524288,
+        "messageRetention": 3600,
+        "encryption": {
+          "enabled": true,
+          "algorithm": "AES-256-GCM",
+          "keyRef": "messaging-encryption-key"
+        }
+      }
+    },
+    {
+      "name": "agents.broadcast.shutdown",
+      "type": "broadcast",
+      "description": "System-wide shutdown notification",
+      "schema": "SystemShutdown",
+      "qos": {
+        "deliveryMode": "at-most-once",
+        "persistent": false,
+        "ordered": false
+      },
+      "config": {
+        "maxMessageSize": 4096,
+        "messageRetention": 0,
+        "deadLetterQueue": false
+      }
+    }
+  ]
+}

package/spec/v0.3.1/schemas/messaging/delivery-receipt.schema.json

@@ -0,0 +1,192 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.1/messaging/delivery-receipt.json",
+  "title": "OSSA Delivery Receipt Schema",
+  "description": "Schema for message delivery receipts in OSSA v0.3.1",
+  "type": "object",
+  "required": [
+    "messageId",
+    "status",
+    "timestamp"
+  ],
+  "properties": {
+    "messageId": {
+      "type": "string",
+      "description": "Original message ID",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "receiptId": {
+      "type": "string",
+      "description": "Unique receipt identifier (UUID v4)",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "accepted",
+        "delivered",
+        "acknowledged",
+        "processed",
+        "failed",
+        "rejected",
+        "expired"
+      ],
+      "description": "Delivery status"
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "Receipt timestamp (ISO 8601 UTC)",
+      "format": "date-time"
+    },
+    "subscriber": {
+      "type": "string",
+      "description": "Subscriber agent ID",
+      "pattern": "^ossa://agents/[a-z0-9-]+$",
+      "examples": [
+        "ossa://agents/code-reviewer"
+      ]
+    },
+    "channel": {
+      "type": "string",
+      "description": "Channel where message was delivered",
+      "pattern": "^agents\\.([a-z0-9-]+\\.)+[a-z0-9-]+$"
+    },
+    "deliveryAttempt": {
+      "type": "integer",
+      "description": "Delivery attempt number (1-based)",
+      "minimum": 1
+    },
+    "processingTime": {
+      "type": "integer",
+      "description": "Message processing time in milliseconds",
+      "minimum": 0
+    },
+    "error": {
+      "$ref": "#/definitions/DeliveryError",
+      "description": "Error details (only present when status is failed or rejected)"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional receipt metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "DeliveryError": {
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Error code",
+          "examples": [
+            "TIMEOUT",
+            "HANDLER_ERROR",
+            "VALIDATION_FAILED",
+            "SUBSCRIBER_UNAVAILABLE"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable error message",
+          "maxLength": 512
+        },
+        "details": {
+          "type": "object",
+          "description": "Additional error details",
+          "additionalProperties": true
+        },
+        "stackTrace": {
+          "type": "string",
+          "description": "Stack trace (only in development/debug mode)",
+          "maxLength": 4096
+        },
+        "retryable": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether delivery can be retried"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "messageId": "550e8400-e29b-41d4-a716-446655440000",
+      "receiptId": "660f9511-f3ac-52e5-b827-557766551111",
+      "status": "acknowledged",
+      "timestamp": "2025-12-18T14:32:16.234Z",
+      "subscriber": "ossa://agents/code-reviewer",
+      "channel": "agents.tasks.assigned",
+      "deliveryAttempt": 1,
+      "processingTime": 1234,
+      "metadata": {
+        "handlerName": "handleTaskAssigned",
+        "queueTime": 45
+      }
+    },
+    {
+      "messageId": "770e8400-e29b-41d4-a716-446655440001",
+      "receiptId": "880f9511-f3ac-52e5-b827-557766551112",
+      "status": "failed",
+      "timestamp": "2025-12-18T14:35:00.567Z",
+      "subscriber": "ossa://agents/code-reviewer",
+      "channel": "agents.tasks.assigned",
+      "deliveryAttempt": 3,
+      "processingTime": 30000,
+      "error": {
+        "code": "TIMEOUT",
+        "message": "Handler exceeded 30s timeout",
+        "details": {
+          "timeout": 30000,
+          "actualDuration": 30124
+        },
+        "retryable": true
+      }
+    },
+    {
+      "messageId": "990e8400-e29b-41d4-a716-446655440002",
+      "receiptId": "aa0f9511-f3ac-52e5-b827-557766551113",
+      "status": "rejected",
+      "timestamp": "2025-12-18T14:40:00.890Z",
+      "subscriber": "ossa://agents/code-reviewer",
+      "channel": "agents.tasks.assigned",
+      "deliveryAttempt": 1,
+      "processingTime": 15,
+      "error": {
+        "code": "VALIDATION_FAILED",
+        "message": "Message payload failed schema validation",
+        "details": {
+          "schemaErrors": [
+            {
+              "field": "payload.taskId",
+              "error": "Required field missing"
+            }
+          ]
+        },
+        "retryable": false
+      }
+    },
+    {
+      "messageId": "bb0e8400-e29b-41d4-a716-446655440003",
+      "receiptId": "cc0f9511-f3ac-52e5-b827-557766551114",
+      "status": "expired",
+      "timestamp": "2025-12-18T15:32:15.123Z",
+      "channel": "agents.tasks.assigned",
+      "deliveryAttempt": 0,
+      "error": {
+        "code": "TTL_EXPIRED",
+        "message": "Message exceeded time-to-live",
+        "details": {
+          "ttl": 3600,
+          "messageAge": 3605
+        },
+        "retryable": false
+      }
+    }
+  ]
+}

package/spec/v0.3.1/schemas/messaging/message.schema.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.1/messaging/message.json",
+  "title": "OSSA Message Schema",
+  "description": "Schema for Agent-to-Agent messages in OSSA v0.3.1",
+  "type": "object",
+  "required": [
+    "id",
+    "channel",
+    "sender",
+    "timestamp",
+    "type",
+    "payload"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique message identifier (UUID v4)",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
+      "examples": [
+        "550e8400-e29b-41d4-a716-446655440000"
+      ]
+    },
+    "channel": {
+      "type": "string",
+      "description": "Target channel name (supports wildcards for subscriptions)",
+      "pattern": "^agents\\.(([a-z0-9-]+|\\*)\\.)+([a-z0-9-]+|#)$",
+      "minLength": 3,
+      "maxLength": 256,
+      "examples": [
+        "agents.tasks.assigned",
+        "agents.code-reviewer.completed",
+        "agents.broadcast.shutdown"
+      ]
+    },
+    "sender": {
+      "type": "string",
+      "description": "Sender agent ID (OSSA URI format)",
+      "pattern": "^ossa://agents/[a-z0-9-]+$",
+      "examples": [
+        "ossa://agents/task-orchestrator",
+        "ossa://agents/code-reviewer"
+      ]
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "Message creation timestamp (ISO 8601 UTC)",
+      "format": "date-time",
+      "examples": [
+        "2025-12-18T14:32:15.123Z"
+      ]
+    },
+    "type": {
+      "type": "string",
+      "description": "Message type identifier (PascalCase)",
+      "pattern": "^[A-Z][a-zA-Z0-9]*$",
+      "minLength": 1,
+      "maxLength": 64,
+      "examples": [
+        "TaskAssigned",
+        "TaskCompleted",
+        "StatusUpdate",
+        "ErrorOccurred"
+      ]
+    },
+    "payload": {
+      "type": "object",
+      "description": "Message content (structure validated by type schema)",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "taskId": "task-001",
+          "description": "Review PR #132"
+        }
+      ]
+    },
+    "metadata": {
+      "$ref": "#/definitions/MessageMetadata",
+      "description": "Optional message metadata"
+    },
+    "qos": {
+      "$ref": "#/definitions/QualityOfService",
+      "description": "Delivery guarantees (defaults to at-least-once)"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "MessageMetadata": {
+      "type": "object",
+      "description": "Message metadata for routing and processing",
+      "properties": {
+        "correlationId": {
+          "type": "string",
+          "description": "Correlation ID for request-response patterns",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "replyTo": {
+          "type": "string",
+          "description": "Channel name for response messages",
+          "pattern": "^agents\\.([a-z0-9-]+\\.)+[a-z0-9-]+$"
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["low", "normal", "high", "critical"],
+          "default": "normal",
+          "description": "Message priority for routing and processing"
+        },
+        "ttl": {
+          "type": "integer",
+          "description": "Time-to-live in seconds (message expires after this duration)",
+          "minimum": 1,
+          "maximum": 86400
+        },
+        "contentType": {
+          "type": "string",
+          "description": "MIME type of payload content",
+          "default": "application/json",
+          "examples": [
+            "application/json",
+            "application/xml",
+            "text/plain"
+          ]
+        },
+        "contentEncoding": {
+          "type": "string",
+          "description": "Encoding of payload content",
+          "default": "utf-8",
+          "examples": [
+            "utf-8",
+            "base64",
+            "gzip"
+          ]
+        },
+        "headers": {
+          "type": "object",
+          "description": "Custom headers for tracing, authentication, etc.",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "examples": [
+            {
+              "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
+              "user-agent": "OSSA/0.3.1"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "QualityOfService": {
+      "type": "object",
+      "description": "Message delivery guarantees",
+      "properties": {
+        "deliveryMode": {
+          "type": "string",
+          "enum": ["at-most-once", "at-least-once", "exactly-once"],
+          "default": "at-least-once",
+          "description": "Delivery guarantee level"
+        },
+        "persistent": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether message survives broker restarts"
+        },
+        "ordered": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether message order is preserved within channel"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "channel": "agents.tasks.assigned",
+      "sender": "ossa://agents/task-orchestrator",
+      "timestamp": "2025-12-18T14:32:15.123Z",
+      "type": "TaskAssigned",
+      "payload": {
+        "taskId": "task-001",
+        "assignedTo": "ossa://agents/code-reviewer",
+        "description": "Review PR #132",
+        "priority": "high",
+        "deadline": "2025-12-18T18:00:00Z"
+      },
+      "metadata": {
+        "correlationId": "pr-132",
+        "replyTo": "agents.orchestrator.responses",
+        "priority": "high",
+        "ttl": 3600,
+        "headers": {
+          "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+        }
+      },
+      "qos": {
+        "deliveryMode": "at-least-once",
+        "persistent": true,
+        "ordered": true
+      }
+    }
+  ]
+}