@bluefly/openstandardagents 0.3.1 → 0.3.2

package/spec/v0.3.2/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.2/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
+      }
+    }
+  ]
+}

package/spec/v0.3.2/schemas/messaging/subscription.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openstandardagents.org/schemas/v0.3.1/messaging/subscription.json",
+  "title": "OSSA Subscription Schema",
+  "description": "Schema for agent message subscriptions in OSSA v0.3.1",
+  "type": "object",
+  "required": [
+    "channel",
+    "handler"
+  ],
+  "properties": {
+    "channel": {
+      "type": "string",
+      "description": "Channel name or pattern (supports wildcards)",
+      "pattern": "^agents\\.(([a-z0-9-]+|\\*)\\.)+([a-z0-9-]+|#)$",
+      "minLength": 3,
+      "maxLength": 256,
+      "examples": [
+        "agents.tasks.assigned",
+        "agents.*.completed",
+        "agents.#"
+      ]
+    },
+    "schema": {
+      "type": "string",
+      "description": "Expected message schema for validation",
+      "examples": [
+        "TaskAssigned",
+        "TaskCompleted"
+      ]
+    },
+    "handler": {
+      "type": "string",
+      "description": "Handler function name in agent implementation",
+      "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+      "examples": [
+        "handleTaskAssigned",
+        "onTaskCompleted",
+        "processMessage"
+      ]
+    },
+    "filter": {
+      "type": "object",
+      "description": "Message filter criteria (JSONPath-like syntax)",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "payload.assignedTo": "ossa://agents/code-reviewer",
+          "payload.priority": "high"
+        }
+      ]
+    },
+    "priority": {
+      "type": "string",
+      "enum": ["low", "normal", "high", "critical"],
+      "default": "normal",
+      "description": "Subscription processing priority"
+    },
+    "config": {
+      "$ref": "#/definitions/SubscriptionConfig",
+      "description": "Subscription-specific configuration"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Custom subscription metadata",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "SubscriptionConfig": {
+      "type": "object",
+      "description": "Subscription configuration options",
+      "properties": {
+        "autoAcknowledge": {
+          "type": "boolean",
+          "default": false,
+          "description": "Automatically acknowledge messages after handler completes"
+        },
+        "maxConcurrentMessages": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 10,
+          "description": "Maximum concurrent message processing"
+        },
+        "prefetchCount": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 10,
+          "description": "Number of messages to prefetch from broker"
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 300000,
+          "default": 30000,
+          "description": "Handler timeout in milliseconds"
+        },
+        "retryOnError": {
+          "type": "boolean",
+          "default": true,
+          "description": "Retry message on handler error"
+        },
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100,
+          "default": 3,
+          "description": "Maximum retry attempts for failed handlers"
+        },
+        "retryBackoff": {
+          "type": "object",
+          "description": "Retry backoff configuration",
+          "properties": {
+            "strategy": {
+              "type": "string",
+              "enum": ["none", "linear", "exponential"],
+              "default": "exponential"
+            },
+            "initialDelay": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 60000,
+              "default": 1000,
+              "description": "Initial retry delay in milliseconds"
+            },
+            "maxDelay": {
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 300000,
+              "default": 30000,
+              "description": "Maximum retry delay in milliseconds"
+            },
+            "multiplier": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 10,
+              "default": 2,
+              "description": "Backoff multiplier for exponential strategy"
+            }
+          },
+          "additionalProperties": false
+        },
+        "deadLetterQueue": {
+          "type": "boolean",
+          "default": true,
+          "description": "Send failed messages to DLQ after max retries"
+        },
+        "messageOrdering": {
+          "type": "string",
+          "enum": ["strict", "relaxed", "none"],
+          "default": "relaxed",
+          "description": "Message ordering guarantee"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "channel": "agents.tasks.assigned",
+      "schema": "TaskAssigned",
+      "handler": "handleTaskAssigned",
+      "filter": {
+        "payload.assignedTo": "ossa://agents/code-reviewer"
+      },
+      "priority": "high",
+      "config": {
+        "autoAcknowledge": false,
+        "maxConcurrentMessages": 5,
+        "prefetchCount": 10,
+        "timeout": 60000,
+        "retryOnError": true,
+        "maxRetries": 5,
+        "retryBackoff": {
+          "strategy": "exponential",
+          "initialDelay": 1000,
+          "maxDelay": 30000,
+          "multiplier": 2
+        },
+        "deadLetterQueue": true,
+        "messageOrdering": "strict"
+      }
+    },
+    {
+      "channel": "agents.*.completed",
+      "schema": "TaskCompleted",
+      "handler": "onAnyTaskCompleted",
+      "priority": "normal",
+      "config": {
+        "autoAcknowledge": true,
+        "maxConcurrentMessages": 20,
+        "timeout": 5000,
+        "retryOnError": false,
+        "messageOrdering": "none"
+      }
+    },
+    {
+      "channel": "agents.broadcast.shutdown",
+      "schema": "SystemShutdown",
+      "handler": "handleShutdown",
+      "priority": "critical",
+      "config": {
+        "autoAcknowledge": true,
+        "maxConcurrentMessages": 1,
+        "timeout": 10000,
+        "retryOnError": false,
+        "deadLetterQueue": false
+      }
+    }
+  ]
+}