mailagents-email-runtime/docs/runtime-compatibility.schema.json at main · haocn-ops/mailagents-email-runtime · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
{
  "$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
}