{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Mailagents Agent Compatibility Contract",
  "type": "object",
  "required": [
    "contract",
    "discovery",
    "evolution",
    "guarantees",
    "mcp",
    "workflows",
    "errors",
    "routes"
  ],
  "properties": {
    "contract": {
      "type": "object",
      "required": [
        "name",
        "version",
        "stability",
        "changelogPath"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "stability": {
          "type": "string"
        },
        "changelogPath": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "discovery": {
      "type": "object",
      "required": [
        "runtimeMetadataPath",
        "compatibilityPath",
        "compatibilitySchemaPath",
        "mcpInitializeEmbedsRuntimeMetadata",
        "toolsListScopeFiltered"
      ],
      "properties": {
        "runtimeMetadataPath": {
          "type": "string"
        },
        "compatibilityPath": {
          "type": "string"
        },
        "compatibilitySchemaPath": {
          "type": "string"
        },
        "adminMcpPath": {
          "type": "string"
        },
        "mcpInitializeEmbedsRuntimeMetadata": {
          "type": "boolean"
        },
        "toolsListScopeFiltered": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "evolution": {
      "type": "object",
      "required": [
        "versioningPolicy",
        "deprecationPolicy",
        "deprecatedFields"
      ],
      "properties": {
        "versioningPolicy": {
          "type": "object",
          "required": [
            "patchSafeChanges",
            "compatibilityVersionBumpTriggers"
          ],
          "properties": {
            "patchSafeChanges": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "compatibilityVersionBumpTriggers": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "additionalProperties": false
        },
        "deprecationPolicy": {
          "type": "object",
          "required": [
            "announcedVia",
            "minimumNotice",
            "removalRule"
          ],
          "properties": {
            "announcedVia": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "minimumNotice": {
              "type": "string"
            },
            "removalRule": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "deprecatedFields": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "path",
              "status"
            ],
            "properties": {
              "path": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": [
                  "deprecated"
                ]
              },
              "replacement": {
                "type": "string"
              },
              "removalVersion": {
                "type": "string"
              },
              "note": {
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "guarantees": {
      "type": "object",
      "required": [
        "stableRuntimeFields",
        "stableToolAnnotations",
        "stableErrorCodes",
        "idempotentOperations"
      ],
      "properties": {
        "stableRuntimeFields": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stableToolAnnotations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "stableErrorCodes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "idempotentOperations": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "mcp": {
      "type": "object",
      "required": [
        "protocolVersion",
        "methods",
        "tools"
      ],
      "properties": {
        "protocolVersion": {
          "type": "string"
        },
        "methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "name",
              "requiredScopes",
              "sendAdditionalScopes",
              "composite",
              "supportsPartialAuthorization",
              "category",
              "recommendedForMailboxAgents",
              "riskLevel",
              "sideEffecting",
              "humanReviewRequired"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "requiredScopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "sendAdditionalScopes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "composite": {
                "type": "boolean"
              },
              "supportsPartialAuthorization": {
                "type": "boolean"
              },
              "category": {
                "type": "string",
                "enum": [
                  "provisioning",
                  "policy",
                  "task_read",
                  "mail_read",
                  "thread_read",
                  "draft_control",
                  "mail_send",
                  "mail_reply",
                  "recovery"
                ]
              },
              "recommendedForMailboxAgents": {
                "type": "boolean"
              },
              "riskLevel": {
                "type": "string",
                "enum": [
                  "read",
                  "write",
                  "high_risk",
                  "privileged"
                ]
              },
              "sideEffecting": {
                "type": "boolean"
              },
              "humanReviewRequired": {
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "workflows": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "compositeTool",
          "sideEffects"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "compositeTool": {
            "type": [
              "string",
              "null"
            ]
          },
          "sideEffects": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      }
    },
    "admin": {
      "type": "object",
      "required": [
        "mcp"
      ],
      "properties": {
        "mcp": {
          "type": "object",
          "required": [
            "path",
            "auth",
            "methods",
            "workflows"
          ],
          "properties": {
            "path": {
              "type": "string"
            },
            "auth": {
              "type": "object",
              "required": [
                "type",
                "header"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "header"
                  ]
                },
                "header": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            },
            "methods": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "workflows": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "name",
                  "description",
                  "goal",
                  "compositeTool",
                  "categories",
                  "recommendedToolSequence",
                  "sideEffects",
                  "stopConditions"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "goal": {
                    "type": "string"
                  },
                  "compositeTool": {
                    "type": "string"
                  },
                  "categories": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "token_admin",
                        "registry_admin",
                        "policy_admin",
                        "debug",
                        "suppression"
                      ]
                    }
                  },
                  "recommendedToolSequence": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "sideEffects": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "stopConditions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "code",
          "category",
          "retryable",
          "description"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "routes": {
      "type": "object",
      "required": [
        "adminEnabled",
        "debugEnabled"
      ],
      "properties": {
        "adminEnabled": {
          "type": "boolean"
        },
        "debugEnabled": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "delivery": {
      "type": "object",
      "required": [
        "outboundProvider"
      ],
      "properties": {
        "outboundProvider": {
          "type": "string",
          "enum": [
            "ses",
            "resend"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}