@agentspec/sdk 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/README.md +46 -0
  2. package/dist/evidence-points-C6j4PSsQ.d.cts +1139 -0
  3. package/dist/evidence-points-C6j4PSsQ.d.ts +1139 -0
  4. package/dist/index.cjs +1727 -345
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +1026 -2549
  7. package/dist/index.d.ts +1026 -2549
  8. package/dist/index.js +1678 -344
  9. package/dist/index.js.map +1 -1
  10. package/dist/runtime.cjs +930 -0
  11. package/dist/runtime.cjs.map +1 -0
  12. package/dist/runtime.d.cts +63 -0
  13. package/dist/runtime.d.ts +63 -0
  14. package/dist/runtime.js +921 -0
  15. package/dist/runtime.js.map +1 -0
  16. package/package.json +15 -8
  17. package/schemas/evidence/v1/contract.schema.json +2078 -0
  18. package/schemas/evidence/v1/fixtures/drifted/EvalResult.n-as-string.json +1 -0
  19. package/schemas/evidence/v1/fixtures/drifted/EvalResult.pass-rate-above-one.json +1 -0
  20. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.bad-sha.json +1 -0
  21. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.extra-field.json +1 -0
  22. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.fail-without-reason.json +1 -0
  23. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.missing-ttl.json +1 -0
  24. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.not-verifiable-without-reason.json +1 -0
  25. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-epoch.json +1 -0
  26. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-out-of-range.json +1 -0
  27. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.observed-at-space-separated.json +1 -0
  28. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.sample-size-boolean.json +1 -0
  29. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.ttl-as-string.json +1 -0
  30. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-collector.json +1 -0
  31. package/schemas/evidence/v1/fixtures/drifted/EvidenceRecord.unknown-source.json +1 -0
  32. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-contract-version.json +1 -0
  33. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.bad-record.json +1 -0
  34. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.point-records-over-limit.json +1 -0
  35. package/schemas/evidence/v1/fixtures/drifted/Heartbeat.with-gap.json +1 -0
  36. package/schemas/evidence/v1/fixtures/drifted/ReadinessFinding.bad-severity.json +1 -0
  37. package/schemas/evidence/v1/fixtures/drifted/SidecarPush.missing-sha.json +1 -0
  38. package/schemas/evidence/v1/fixtures/drifted/TrustPolicy.lenient.json +1 -0
  39. package/schemas/evidence/v1/fixtures/valid/EvalResult.live.json +1 -0
  40. package/schemas/evidence/v1/fixtures/valid/EvalResult.null-dataset.json +1 -0
  41. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.fail.json +1 -0
  42. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.null-collector.json +1 -0
  43. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass-null-reason.json +1 -0
  44. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.pass.json +1 -0
  45. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.timezone-offset.json +1 -0
  46. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.unknown-reason-code.json +1 -0
  47. package/schemas/evidence/v1/fixtures/valid/EvidenceRecord.with-collector.json +1 -0
  48. package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-null.json +1 -0
  49. package/schemas/evidence/v1/fixtures/valid/Heartbeat.contract-version.json +1 -0
  50. package/schemas/evidence/v1/fixtures/valid/Heartbeat.evidence-points.json +1 -0
  51. package/schemas/evidence/v1/fixtures/valid/Heartbeat.full.json +1 -0
  52. package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk-no-records.json +1 -0
  53. package/schemas/evidence/v1/fixtures/valid/Heartbeat.sdk.json +1 -0
  54. package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.open-code.json +1 -0
  55. package/schemas/evidence/v1/fixtures/valid/ReadinessFinding.with-subject.json +1 -0
  56. package/schemas/evidence/v1/fixtures/valid/SidecarPush.declared.json +1 -0
  57. package/schemas/evidence/v1/fixtures/valid/TrustPolicy.standard.json +1 -0
  58. package/schemas/evidence/v1/fixtures/valid/TrustPolicy.strict.json +1 -0
  59. package/schemas/grader/v1/fixtures/accepts-fractional-seconds.json +62 -0
  60. package/schemas/grader/v1/fixtures/accepts-leap-day-in-year-below-100.json +62 -0
  61. package/schemas/grader/v1/fixtures/accepts-more-than-6-fractional-digits.json +62 -0
  62. package/schemas/grader/v1/fixtures/accepts-numeric-offset.json +62 -0
  63. package/schemas/grader/v1/fixtures/all-records-must-pass.json +58 -0
  64. package/schemas/grader/v1/fixtures/below-threshold-not-graded.json +61 -0
  65. package/schemas/grader/v1/fixtures/derived-rule-fails-when-a-parent-fails.json +67 -0
  66. package/schemas/grader/v1/fixtures/derived-rule-follows-memory-write-parent.json +43 -0
  67. package/schemas/grader/v1/fixtures/derived-rule-passes-with-its-parents.json +64 -0
  68. package/schemas/grader/v1/fixtures/derived-rule-unverified-when-a-parent-has-no-evidence.json +51 -0
  69. package/schemas/grader/v1/fixtures/expired-record-is-stale.json +66 -0
  70. package/schemas/grader/v1/fixtures/fail-beats-not-verifiable.json +62 -0
  71. package/schemas/grader/v1/fixtures/grade-band-b.json +62 -0
  72. package/schemas/grader/v1/fixtures/independent-from-listed-collector-is-admitted.json +39 -0
  73. package/schemas/grader/v1/fixtures/independent-from-unlisted-collector-is-rejected.json +47 -0
  74. package/schemas/grader/v1/fixtures/low-severity-coverage-only.json +90 -0
  75. package/schemas/grader/v1/fixtures/malformed-point-is-ignored.json +67 -0
  76. package/schemas/grader/v1/fixtures/never-admitted-sources-standard.json +196 -0
  77. package/schemas/grader/v1/fixtures/never-admitted-sources-strict.json +196 -0
  78. package/schemas/grader/v1/fixtures/not-admitted-outranks-mismatch.json +64 -0
  79. package/schemas/grader/v1/fixtures/not-verifiable-ignored-when-one-passes.json +58 -0
  80. package/schemas/grader/v1/fixtures/not-verifiable-only-keeps-reason.json +71 -0
  81. package/schemas/grader/v1/fixtures/not-wired-point-drops-a-fail-when-no-point-of-the-rule-is-wired.json +59 -0
  82. package/schemas/grader/v1/fixtures/not-wired-point-drops-a-wired-point-pass.json +87 -0
  83. package/schemas/grader/v1/fixtures/not-wired-point-drops-its-own-earlier-fail-when-another-point-is-wired.json +70 -0
  84. package/schemas/grader/v1/fixtures/not-wired-point-ignores-a-wired-point-fail-without-the-rule-id.json +69 -0
  85. package/schemas/grader/v1/fixtures/not-wired-point-keeps-a-wired-point-fail.json +79 -0
  86. package/schemas/grader/v1/fixtures/not-wired-point-keeps-independent-evidence.json +64 -0
  87. package/schemas/grader/v1/fixtures/not-wired-point-never-passes.json +107 -0
  88. package/schemas/grader/v1/fixtures/offline-record-is-not-admitted-yet.json +47 -0
  89. package/schemas/grader/v1/fixtures/record-without-collector-is-admitted-until-producers-set-it.json +38 -0
  90. package/schemas/grader/v1/fixtures/records-without-rule-id-never-graded.json +62 -0
  91. package/schemas/grader/v1/fixtures/rejects-compact-timestamp.json +56 -0
  92. package/schemas/grader/v1/fixtures/rejects-hour-24-lowercase-separator.json +56 -0
  93. package/schemas/grader/v1/fixtures/rejects-hour-24-space-separator.json +56 -0
  94. package/schemas/grader/v1/fixtures/rejects-hour-24.json +56 -0
  95. package/schemas/grader/v1/fixtures/rejects-impossible-date-feb-29.json +56 -0
  96. package/schemas/grader/v1/fixtures/rejects-lowercase-t.json +56 -0
  97. package/schemas/grader/v1/fixtures/rejects-lowercase-z.json +56 -0
  98. package/schemas/grader/v1/fixtures/rejects-offset-hours-above-23.json +56 -0
  99. package/schemas/grader/v1/fixtures/rejects-offset-minutes-above-59.json +56 -0
  100. package/schemas/grader/v1/fixtures/rejects-offsetless-timestamp.json +56 -0
  101. package/schemas/grader/v1/fixtures/rejects-space-separator.json +56 -0
  102. package/schemas/grader/v1/fixtures/rejects-year-zero.json +56 -0
  103. package/schemas/grader/v1/fixtures/rounds-coverage-before-the-threshold.json +850 -0
  104. package/schemas/grader/v1/fixtures/rounds-verified-before-the-band.json +674 -0
  105. package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-admitted-standard.json +39 -0
  106. package/schemas/grader/v1/fixtures/sdk-observed-from-evidence-point-rule-is-not-admitted-strict.json +47 -0
  107. package/schemas/grader/v1/fixtures/sdk-observed-standard.json +58 -0
  108. package/schemas/grader/v1/fixtures/sdk-observed-strict.json +66 -0
  109. package/schemas/grader/v1/fixtures/sdk-observed-without-evidence-point-source-is-rejected.json +47 -0
  110. package/schemas/grader/v1/fixtures/sdk-only-agent-all-points-fired.json +116 -0
  111. package/schemas/grader/v1/fixtures/stale-outranks-mismatch.json +64 -0
  112. package/schemas/grader/v1/fixtures/strict-admits-independent.json +39 -0
  113. package/schemas/grader/v1/fixtures/sub-millisecond-expiry-boundary.json +38 -0
  114. package/schemas/v1/agent.schema.json +372 -198
@@ -29,18 +29,18 @@
29
29
  "minLength": 1
30
30
  },
31
31
  "tags": {
32
+ "description": "Free-form tags for filtering and discovery (e.g. [\"finance\", \"rag\", \"internal\"]).",
32
33
  "type": "array",
33
34
  "items": {
34
35
  "type": "string"
35
- },
36
- "description": "Free-form tags for filtering and discovery (e.g. [\"finance\", \"rag\", \"internal\"])."
36
+ }
37
37
  },
38
38
  "author": {
39
39
  "type": "string"
40
40
  },
41
41
  "license": {
42
- "type": "string",
43
- "description": "SPDX license identifier (e.g. \"MIT\", \"Apache-2.0\", \"proprietary\")."
42
+ "description": "SPDX license identifier (e.g. \"MIT\", \"Apache-2.0\", \"proprietary\").",
43
+ "type": "string"
44
44
  }
45
45
  },
46
46
  "required": [
@@ -68,33 +68,38 @@
68
68
  "type": "string",
69
69
  "description": "Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
70
70
  },
71
+ "baseUrl": {
72
+ "description": "Override the provider endpoint with an OpenAI-compatible base URL (vLLM, Ollama, LiteLLM, an internal proxy, a mock LLM). A literal http(s) URL with a host (checked by the loader, not expressible in JSON Schema) or \"$env:VAR\". When set, the gateway treats the model as a custom OpenAI-compatible provider for any \"provider\" value except \"anthropic\", whose baseUrl is an Anthropic Messages endpoint without \"/v1\" (the gateway adds it). Omit to use the provider default.",
73
+ "type": "string",
74
+ "pattern": "^(\\$env:[A-Za-z_][A-Za-z0-9_]*|https?:\\/\\/.+)$"
75
+ },
71
76
  "parameters": {
72
77
  "type": "object",
73
78
  "properties": {
74
79
  "temperature": {
80
+ "description": "Sampling temperature. 0 = deterministic/focused, 1 = balanced, 2 = highly creative. Most providers recommend 0–1 for production agents.",
75
81
  "type": "number",
76
82
  "minimum": 0,
77
- "maximum": 2,
78
- "description": "Sampling temperature. 0 = deterministic/focused, 1 = balanced, 2 = highly creative. Most providers recommend 0–1 for production agents."
83
+ "maximum": 2
79
84
  },
80
85
  "maxTokens": {
86
+ "description": "Maximum tokens in the model response. Controls cost and latency. Check model context window limits.",
81
87
  "type": "integer",
82
- "minimum": 1,
83
- "description": "Maximum tokens in the model response. Controls cost and latency. Check model context window limits."
88
+ "minimum": 1
84
89
  },
85
90
  "topP": {
91
+ "description": "Nucleus sampling threshold. The model samples from the smallest set of tokens whose cumulative probability exceeds topP. Alternative to temperature — do not set both.",
86
92
  "type": "number",
87
93
  "minimum": 0,
88
- "maximum": 1,
89
- "description": "Nucleus sampling threshold. The model samples from the smallest set of tokens whose cumulative probability exceeds topP. Alternative to temperature — do not set both."
94
+ "maximum": 1
90
95
  },
91
96
  "frequencyPenalty": {
92
- "type": "number",
93
- "description": "Penalises tokens that have already appeared frequently in the output (-2.0–2.0). Positive values reduce repetition."
97
+ "description": "Penalises tokens that have already appeared frequently in the output (-2.0–2.0). Positive values reduce repetition.",
98
+ "type": "number"
94
99
  },
95
100
  "presencePenalty": {
96
- "type": "number",
97
- "description": "Penalises tokens that appear at all in the output so far (-2.0–2.0). Positive values encourage the model to introduce new topics."
101
+ "description": "Penalises tokens that appear at all in the output so far (-2.0–2.0). Positive values encourage the model to introduce new topics.",
102
+ "type": "number"
98
103
  }
99
104
  },
100
105
  "additionalProperties": false
@@ -114,7 +119,13 @@
114
119
  "type": "string",
115
120
  "description": "Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
116
121
  },
122
+ "baseUrl": {
123
+ "description": "Override the provider endpoint with an OpenAI-compatible base URL (vLLM, Ollama, LiteLLM, an internal proxy, a mock LLM). A literal http(s) URL with a host (checked by the loader, not expressible in JSON Schema) or \"$env:VAR\". When set, the gateway treats the model as a custom OpenAI-compatible provider for any \"provider\" value except \"anthropic\", whose baseUrl is an Anthropic Messages endpoint without \"/v1\" (the gateway adds it). Omit to use the provider default.",
124
+ "type": "string",
125
+ "pattern": "^(\\$env:[A-Za-z_][A-Za-z0-9_]*|https?:\\/\\/.+)$"
126
+ },
117
127
  "triggerOn": {
128
+ "description": "Conditions that trigger failover to this model. Omit to use the fallback for all errors.",
118
129
  "type": "array",
119
130
  "items": {
120
131
  "type": "string",
@@ -124,14 +135,49 @@
124
135
  "error_5xx",
125
136
  "error_4xx"
126
137
  ]
127
- },
128
- "description": "Conditions that trigger failover to this model. Omit to use the fallback for all errors."
138
+ }
129
139
  },
130
140
  "maxRetries": {
141
+ "description": "Number of retry attempts before failing over. Defaults to 0 (immediate failover).",
131
142
  "type": "integer",
132
143
  "minimum": 0,
133
- "maximum": 10,
134
- "description": "Number of retry attempts before failing over. Defaults to 0 (immediate failover)."
144
+ "maximum": 10
145
+ },
146
+ "pricing": {
147
+ "type": "object",
148
+ "properties": {
149
+ "input": {
150
+ "type": "number",
151
+ "minimum": 0,
152
+ "description": "USD per 1M input (prompt) tokens."
153
+ },
154
+ "output": {
155
+ "type": "number",
156
+ "minimum": 0,
157
+ "description": "USD per 1M output (completion) tokens."
158
+ },
159
+ "cacheRead": {
160
+ "description": "USD per 1M tokens read from the prompt cache.",
161
+ "type": "number",
162
+ "minimum": 0
163
+ },
164
+ "cacheWrite": {
165
+ "description": "USD per 1M tokens written to the prompt cache.",
166
+ "type": "number",
167
+ "minimum": 0
168
+ },
169
+ "reasoning": {
170
+ "description": "USD per 1M reasoning tokens. The gateway uses the output price when omitted.",
171
+ "type": "number",
172
+ "minimum": 0
173
+ }
174
+ },
175
+ "required": [
176
+ "input",
177
+ "output"
178
+ ],
179
+ "description": "Price of this model in USD per 1M tokens. The gateway uses it instead of its built-in price, so a maxMonthlyUSD budget is spent on models it does not price (e.g. o4-mini). Omit to use the gateway's built-in price.",
180
+ "additionalProperties": false
135
181
  }
136
182
  },
137
183
  "required": [
@@ -141,18 +187,54 @@
141
187
  ],
142
188
  "additionalProperties": false
143
189
  },
190
+ "pricing": {
191
+ "type": "object",
192
+ "properties": {
193
+ "input": {
194
+ "type": "number",
195
+ "minimum": 0,
196
+ "description": "USD per 1M input (prompt) tokens."
197
+ },
198
+ "output": {
199
+ "type": "number",
200
+ "minimum": 0,
201
+ "description": "USD per 1M output (completion) tokens."
202
+ },
203
+ "cacheRead": {
204
+ "description": "USD per 1M tokens read from the prompt cache.",
205
+ "type": "number",
206
+ "minimum": 0
207
+ },
208
+ "cacheWrite": {
209
+ "description": "USD per 1M tokens written to the prompt cache.",
210
+ "type": "number",
211
+ "minimum": 0
212
+ },
213
+ "reasoning": {
214
+ "description": "USD per 1M reasoning tokens. The gateway uses the output price when omitted.",
215
+ "type": "number",
216
+ "minimum": 0
217
+ }
218
+ },
219
+ "required": [
220
+ "input",
221
+ "output"
222
+ ],
223
+ "description": "Price of this model in USD per 1M tokens. The gateway uses it instead of its built-in price, so a maxMonthlyUSD budget is spent on models it does not price (e.g. o4-mini). Omit to use the gateway's built-in price.",
224
+ "additionalProperties": false
225
+ },
144
226
  "costControls": {
145
227
  "type": "object",
146
228
  "properties": {
147
229
  "maxMonthlyUSD": {
230
+ "description": "Hard monthly spend cap in USD. Requests are rejected once this limit is reached.",
148
231
  "type": "number",
149
- "exclusiveMinimum": 0,
150
- "description": "Hard monthly spend cap in USD. Requests are rejected once this limit is reached."
232
+ "exclusiveMinimum": 0
151
233
  },
152
234
  "alertAtUSD": {
235
+ "description": "Send an alert when cumulative monthly spend crosses this USD threshold. Must be less than maxMonthlyUSD.",
153
236
  "type": "number",
154
- "exclusiveMinimum": 0,
155
- "description": "Send an alert when cumulative monthly spend crosses this USD threshold. Must be less than maxMonthlyUSD."
237
+ "exclusiveMinimum": 0
156
238
  }
157
239
  },
158
240
  "additionalProperties": false
@@ -173,15 +255,16 @@
173
255
  "description": "System prompt. Use \"$file:prompts/system.md\" to load from a file (recommended for long prompts), or provide an inline string. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
174
256
  },
175
257
  "fallback": {
176
- "type": "string",
177
- "description": "Inline fallback system prompt used if the primary system prompt file cannot be loaded. Only applies when \"system\" is a $file: reference."
258
+ "description": "Inline fallback system prompt used if the primary system prompt file cannot be loaded. Only applies when \"system\" is a $file: reference.",
259
+ "type": "string"
178
260
  },
179
261
  "hotReload": {
180
- "type": "boolean",
181
262
  "default": false,
182
- "description": "When true, the system prompt file is re-read on every request instead of being cached at startup. Useful for rapid iteration without restarts."
263
+ "description": "When true, the system prompt file is re-read on every request instead of being cached at startup. Useful for rapid iteration without restarts.",
264
+ "type": "boolean"
183
265
  },
184
266
  "variables": {
267
+ "description": "Template variables injected into the system prompt at runtime. Values support reference syntax for secrets and env vars.",
185
268
  "type": "array",
186
269
  "items": {
187
270
  "type": "object",
@@ -200,8 +283,7 @@
200
283
  "value"
201
284
  ],
202
285
  "additionalProperties": false
203
- },
204
- "description": "Template variables injected into the system prompt at runtime. Values support reference syntax for secrets and env vars."
286
+ }
205
287
  }
206
288
  },
207
289
  "required": [
@@ -233,31 +315,31 @@
233
315
  "description": "Human-readable description of what the tool does and when the agent should use it. This text is included in the tool-call prompt."
234
316
  },
235
317
  "module": {
236
- "type": "string",
237
- "description": "Path to the module that implements this tool. Use \"$file:tools/my_tool.py\" syntax. Only required for type \"function\"."
318
+ "description": "Path to the module that implements this tool. Use \"$file:tools/my_tool.py\" syntax. Only required for type \"function\".",
319
+ "type": "string"
238
320
  },
239
321
  "function": {
240
- "type": "string",
241
- "description": "Name of the callable function exported from the module (e.g. \"search\", \"run_query\"). Only required for type \"function\"."
322
+ "description": "Name of the callable function exported from the module (e.g. \"search\", \"run_query\"). Only required for type \"function\".",
323
+ "type": "string"
242
324
  },
243
325
  "annotations": {
244
326
  "type": "object",
245
327
  "properties": {
246
328
  "readOnlyHint": {
247
- "type": "boolean",
248
- "description": "MCP hint: tool does not modify state. Allows clients to show a read-only badge and skip confirmation prompts."
329
+ "description": "MCP hint: tool does not modify state. Allows clients to show a read-only badge and skip confirmation prompts.",
330
+ "type": "boolean"
249
331
  },
250
332
  "destructiveHint": {
251
- "type": "boolean",
252
- "description": "MCP hint: tool may perform irreversible actions (delete, overwrite). Triggers human-in-the-loop approval when humanInTheLoop.approvalRequired includes \"before-destructive-tool\"."
333
+ "description": "MCP hint: tool may perform irreversible actions (delete, overwrite). Triggers human-in-the-loop approval when humanInTheLoop.approvalRequired includes \"before-destructive-tool\".",
334
+ "type": "boolean"
253
335
  },
254
336
  "idempotentHint": {
255
- "type": "boolean",
256
- "description": "MCP hint: calling the tool multiple times with the same inputs produces the same result. Allows safe retries."
337
+ "description": "MCP hint: calling the tool multiple times with the same inputs produces the same result. Allows safe retries.",
338
+ "type": "boolean"
257
339
  },
258
340
  "openWorldHint": {
259
- "type": "boolean",
260
- "description": "MCP hint: tool interacts with systems outside the agent's controlled environment (e.g. the internet). Affects trust level in tool outputs."
341
+ "description": "MCP hint: tool interacts with systems outside the agent's controlled environment (e.g. the internet). Affects trust level in tool outputs.",
342
+ "type": "boolean"
261
343
  }
262
344
  },
263
345
  "additionalProperties": false
@@ -292,37 +374,36 @@
292
374
  "description": "\"stdio\" = spawn a local process (requires \"command\"), \"sse\" = Server-Sent Events over HTTP, \"http\" = streamable HTTP (requires \"url\")."
293
375
  },
294
376
  "command": {
295
- "type": "string",
296
- "description": "Shell command to spawn the MCP server process. Required for transport \"stdio\" (e.g. \"npx\", \"python\")."
377
+ "description": "Shell command to spawn the MCP server process. Required for transport \"stdio\" (e.g. \"npx\", \"python\").",
378
+ "type": "string"
297
379
  },
298
380
  "args": {
381
+ "description": "Arguments passed to the command (e.g. [\"-m\", \"my_mcp_server\"]). Only used for transport \"stdio\".",
299
382
  "type": "array",
300
383
  "items": {
301
384
  "type": "string"
302
- },
303
- "description": "Arguments passed to the command (e.g. [\"-m\", \"my_mcp_server\"]). Only used for transport \"stdio\"."
385
+ }
304
386
  },
305
387
  "url": {
306
- "type": "string",
307
- "format": "uri",
308
- "description": "Base URL of the remote MCP server. Required for transport \"sse\" or \"http\". Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
388
+ "description": "Base URL of the remote MCP server. Required for transport \"sse\" or \"http\". Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
389
+ "type": "string"
309
390
  },
310
391
  "env": {
392
+ "description": "Environment variables injected into the MCP server process. Values support reference syntax. Use \"$env:API_KEY\" to forward secrets without hardcoding.",
311
393
  "type": "object",
312
394
  "additionalProperties": {
313
395
  "type": "string"
314
- },
315
- "description": "Environment variables injected into the MCP server process. Values support reference syntax. Use \"$env:API_KEY\" to forward secrets without hardcoding."
396
+ }
316
397
  },
317
398
  "healthCheck": {
318
399
  "type": "object",
319
400
  "properties": {
320
401
  "timeoutSeconds": {
402
+ "default": 5,
403
+ "description": "Seconds to wait for the MCP server to respond during health checks. Increase for slow-starting processes.",
321
404
  "type": "integer",
322
405
  "minimum": 1,
323
- "maximum": 60,
324
- "default": 5,
325
- "description": "Seconds to wait for the MCP server to respond during health checks. Increase for slow-starting processes."
406
+ "maximum": 60
326
407
  }
327
408
  },
328
409
  "additionalProperties": false
@@ -356,23 +437,23 @@
356
437
  ]
357
438
  },
358
439
  "maxTurns": {
440
+ "description": "Maximum number of conversation turns (user + assistant message pairs) to retain in context. Older turns are evicted first. Use with maxTokens for dual-bounded windows.",
359
441
  "type": "integer",
360
- "minimum": 1,
361
- "description": "Maximum number of conversation turns (user + assistant message pairs) to retain in context. Older turns are evicted first. Use with maxTokens for dual-bounded windows."
442
+ "minimum": 1
362
443
  },
363
444
  "maxTokens": {
445
+ "description": "Maximum total tokens across all retained messages. When exceeded, oldest turns are evicted. Required by MEM-05 compliance rule.",
364
446
  "type": "integer",
365
- "minimum": 1,
366
- "description": "Maximum total tokens across all retained messages. When exceeded, oldest turns are evicted. Required by MEM-05 compliance rule."
447
+ "minimum": 1
367
448
  },
368
449
  "ttlSeconds": {
450
+ "description": "Time-to-live in seconds for memory entries. 0 = session-scoped (cleared when connection closes). Omitting means no expiry — increases PII exposure risk (MEM-02).",
369
451
  "type": "integer",
370
- "minimum": 0,
371
- "description": "Time-to-live in seconds for memory entries. 0 = session-scoped (cleared when connection closes). Omitting means no expiry — increases PII exposure risk (MEM-02)."
452
+ "minimum": 0
372
453
  },
373
454
  "connection": {
374
- "type": "string",
375
- "description": "Connection string for redis or sqlite backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
455
+ "description": "Connection string for redis or sqlite backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
456
+ "type": "string"
376
457
  }
377
458
  },
378
459
  "required": [
@@ -396,13 +477,13 @@
396
477
  "description": "Database connection URI. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
397
478
  },
398
479
  "table": {
399
- "type": "string",
400
- "description": "Table or collection name where agent memories are stored. Defaults to \"agent_memories\" if omitted. Use a per-agent name to avoid cross-agent data leakage."
480
+ "description": "Table or collection name where agent memories are stored. Defaults to \"agent_memories\" if omitted. Use a per-agent name to avoid cross-agent data leakage.",
481
+ "type": "string"
401
482
  },
402
483
  "ttlDays": {
484
+ "description": "Time-to-live in days for long-term memory records. Omitting means no expiry — a compliance risk (MEM-02). Required by GDPR Article 5 data minimisation principle.",
403
485
  "type": "integer",
404
- "minimum": 1,
405
- "description": "Time-to-live in days for long-term memory records. Omitting means no expiry — a compliance risk (MEM-02). Required by GDPR Article 5 data minimisation principle."
486
+ "minimum": 1
406
487
  }
407
488
  },
408
489
  "required": [
@@ -425,12 +506,12 @@
425
506
  ]
426
507
  },
427
508
  "connectionString": {
428
- "type": "string",
429
- "description": "Connection URI for self-hosted backends (pgvector, weaviate, qdrant, chroma). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
509
+ "description": "Connection URI for self-hosted backends (pgvector, weaviate, qdrant, chroma). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
510
+ "type": "string"
430
511
  },
431
512
  "apiKey": {
432
- "type": "string",
433
- "description": "API key for managed backends (Pinecone, Weaviate Cloud). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
513
+ "description": "API key for managed backends (Pinecone, Weaviate Cloud). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
514
+ "type": "string"
434
515
  },
435
516
  "dimension": {
436
517
  "type": "integer",
@@ -438,13 +519,13 @@
438
519
  "description": "Embedding vector dimension. Must exactly match the output dimension of your embedding model (e.g. 1536 for text-embedding-3-small, 768 for nomic-embed-text). Mismatch causes insertion errors."
439
520
  },
440
521
  "topK": {
522
+ "description": "Number of nearest-neighbour results to retrieve per similarity search. Higher values improve recall at the cost of latency and context token usage.",
441
523
  "type": "integer",
442
- "minimum": 1,
443
- "description": "Number of nearest-neighbour results to retrieve per similarity search. Higher values improve recall at the cost of latency and context token usage."
524
+ "minimum": 1
444
525
  },
445
526
  "namespace": {
446
- "type": "string",
447
- "description": "Logical partition within the vector store. Required by MEM-04 to prevent cross-agent data leakage. Recommended value: the agent name (spec.metadata.name)."
527
+ "description": "Logical partition within the vector store. Required by MEM-04 to prevent cross-agent data leakage. Recommended value: the agent name (spec.metadata.name).",
528
+ "type": "string"
448
529
  }
449
530
  },
450
531
  "required": [
@@ -457,20 +538,20 @@
457
538
  "type": "object",
458
539
  "properties": {
459
540
  "piiScrubFields": {
541
+ "description": "PII field names to scrub before writing to long-term or vector memory. Required when longTerm is set (MEM-01). Use recogniser names compatible with your scrubbing library (e.g. Microsoft Presidio entity types): \"email\", \"phone_number\", \"credit_card\", \"iban\", \"ssn\", \"bank_account\", \"passport\", \"drivers_license\", \"person_name\", \"date_of_birth\", \"address\", \"ip_address\", \"api_key\", \"password\", \"medical_record\".",
460
542
  "type": "array",
461
543
  "items": {
462
544
  "type": "string"
463
- },
464
- "description": "PII field names to scrub before writing to long-term or vector memory. Required when longTerm is set (MEM-01). Use recogniser names compatible with your scrubbing library (e.g. Microsoft Presidio entity types): \"email\", \"phone_number\", \"credit_card\", \"iban\", \"ssn\", \"bank_account\", \"passport\", \"drivers_license\", \"person_name\", \"date_of_birth\", \"address\", \"ip_address\", \"api_key\", \"password\", \"medical_record\"."
545
+ }
465
546
  },
466
547
  "auditLog": {
467
- "type": "boolean",
468
548
  "default": false,
469
- "description": "When true, all memory read and write operations are emitted as structured audit log events. Required for long-term memory (MEM-03) and HIPAA/SOC2 compliance."
549
+ "description": "When true, all memory read and write operations are emitted as structured audit log events. Required for long-term memory (MEM-03) and HIPAA/SOC2 compliance.",
550
+ "type": "boolean"
470
551
  },
471
552
  "retentionPolicy": {
472
- "type": "string",
473
- "description": "Named governance or compliance retention policy applied to this agent's memory. Informational label — must be consistent with ttlSeconds/ttlDays on the backend configs. Common values: \"session\" (cleared on disconnect), \"ephemeral\" (never persisted), \"30d\", \"90d\", \"1y\", \"persistent\" (explicit no-expiry opt-in), \"gdpr-30d\" (GDPR Art.5 minimum), \"hipaa-6y\" (HIPAA 45 CFR §164.530), \"pci-dss-1y\" (PCI DSS Req.10.7)."
553
+ "description": "Named governance or compliance retention policy applied to this agent's memory. Informational label — must be consistent with ttlSeconds/ttlDays on the backend configs. Common values: \"session\" (cleared on disconnect), \"ephemeral\" (never persisted), \"30d\", \"90d\", \"1y\", \"persistent\" (explicit no-expiry opt-in), \"gdpr-30d\" (GDPR Art.5 minimum), \"hipaa-6y\" (HIPAA 45 CFR §164.530), \"pci-dss-1y\" (PCI DSS Req.10.7).",
554
+ "type": "string"
474
555
  }
475
556
  },
476
557
  "additionalProperties": false
@@ -524,8 +605,8 @@
524
605
  "type": "string"
525
606
  },
526
607
  "header": {
527
- "type": "string",
528
- "description": "HTTP header name for the API key (e.g. \"X-API-Key\"). Only used when auth type is \"apikey\"."
608
+ "description": "HTTP header name for the API key (e.g. \"X-API-Key\"). Only used when auth type is \"apikey\".",
609
+ "type": "string"
529
610
  }
530
611
  },
531
612
  "required": [
@@ -557,16 +638,16 @@
557
638
  "description": "\"parallel\" = invoked concurrently with other subagents, \"sequential\" = invoked in order after previous subagents complete, \"on-demand\" = only invoked when the agent decides it is needed (triggered by LLM or triggerKeywords)."
558
639
  },
559
640
  "passContext": {
560
- "type": "boolean",
561
641
  "default": false,
562
- "description": "When true, the current conversation thread (messages so far) is forwarded to the subagent as context. Use with care — increases token usage and may leak sensitive conversation history."
642
+ "description": "When true, the current conversation thread (messages so far) is forwarded to the subagent as context. Use with care — increases token usage and may leak sensitive conversation history.",
643
+ "type": "boolean"
563
644
  },
564
645
  "triggerKeywords": {
646
+ "description": "Keywords in user messages that automatically trigger this subagent (only applies when invocation is \"on-demand\"). Case-insensitive substring match.",
565
647
  "type": "array",
566
648
  "items": {
567
649
  "type": "string"
568
- },
569
- "description": "Keywords in user messages that automatically trigger this subagent (only applies when invocation is \"on-demand\"). Case-insensitive substring match."
650
+ }
570
651
  }
571
652
  },
572
653
  "required": [
@@ -594,9 +675,18 @@
594
675
  "minimum": 1,
595
676
  "maximum": 65535
596
677
  },
678
+ "allowedPorts": {
679
+ "description": "Extra ports the agent may listen on besides the sidecar-routed API port (e.g. a platform metrics port). The sidecar reports not-ready while the agent listens on any other non-loopback port.",
680
+ "type": "array",
681
+ "items": {
682
+ "type": "integer",
683
+ "minimum": 1,
684
+ "maximum": 65535
685
+ }
686
+ },
597
687
  "pathPrefix": {
598
- "type": "string",
599
- "description": "URL path prefix applied to all API routes (e.g. \"/api/v1\"). Useful when the agent runs behind a reverse proxy."
688
+ "description": "URL path prefix applied to all API routes (e.g. \"/api/v1\"). Useful when the agent runs behind a reverse proxy.",
689
+ "type": "string"
600
690
  },
601
691
  "auth": {
602
692
  "type": "object",
@@ -611,12 +701,12 @@
611
701
  ]
612
702
  },
613
703
  "jwksUri": {
614
- "type": "string",
615
- "description": "JWKS endpoint URL used to fetch public keys for JWT signature verification (e.g. \"https://your-auth.example.com/.well-known/jwks.json\"). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
704
+ "description": "JWKS endpoint URL used to fetch public keys for JWT signature verification (e.g. \"https://your-auth.example.com/.well-known/jwks.json\"). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
705
+ "type": "string"
616
706
  },
617
707
  "header": {
618
- "type": "string",
619
- "description": "HTTP header name carrying the credential (e.g. \"Authorization\" for JWT bearer, \"X-API-Key\" for apikey auth). Defaults to \"Authorization\"."
708
+ "description": "HTTP header name carrying the credential (e.g. \"Authorization\" for JWT bearer, \"X-API-Key\" for apikey auth). Defaults to \"Authorization\".",
709
+ "type": "string"
620
710
  }
621
711
  },
622
712
  "required": [
@@ -628,73 +718,78 @@
628
718
  "type": "object",
629
719
  "properties": {
630
720
  "requestsPerMinute": {
721
+ "description": "Maximum requests allowed per client per minute. Excess requests receive HTTP 429.",
631
722
  "type": "integer",
632
- "minimum": 1,
633
- "description": "Maximum requests allowed per client per minute. Excess requests receive HTTP 429."
723
+ "minimum": 1
634
724
  },
635
725
  "requestsPerHour": {
726
+ "description": "Maximum requests allowed per client per hour. Excess requests receive HTTP 429.",
636
727
  "type": "integer",
637
- "minimum": 1,
638
- "description": "Maximum requests allowed per client per hour. Excess requests receive HTTP 429."
728
+ "minimum": 1
729
+ },
730
+ "tokensPerMinute": {
731
+ "description": "Maximum LLM tokens the gateway allows per minute. Once the bucket is empty, requests receive HTTP 429.",
732
+ "type": "integer",
733
+ "minimum": 1
639
734
  }
640
735
  },
641
736
  "additionalProperties": false
642
737
  },
643
738
  "streaming": {
644
- "type": "boolean",
645
739
  "default": false,
646
- "description": "When true, the API supports streaming responses (SSE). Set true for conversational agents to reduce perceived latency."
740
+ "description": "When true, the API supports streaming responses (SSE). Set true for conversational agents to reduce perceived latency.",
741
+ "type": "boolean"
647
742
  },
648
743
  "healthEndpoint": {
649
- "type": "string",
650
- "description": "URL path for the health check endpoint (e.g. \"/health\", \"/ready\"). Exposes agentspec health report. Defaults to \"/agentspec/health\" when using the SDK."
744
+ "description": "URL path for the health check endpoint (e.g. \"/health\", \"/ready\"). Exposes agentspec health report. Defaults to \"/agentspec/health\" when using the SDK.",
745
+ "type": "string"
651
746
  },
652
747
  "metricsEndpoint": {
653
- "type": "string",
654
- "description": "URL path where Prometheus-format metrics are exposed (e.g. \"/metrics\"). Required for observability.metrics to be scraped."
748
+ "description": "URL path where Prometheus-format metrics are exposed (e.g. \"/metrics\"). Required for observability.metrics to be scraped.",
749
+ "type": "string"
655
750
  },
656
751
  "corsOrigins": {
752
+ "description": "Allowed CORS origins for browser clients (e.g. [\"https://app.example.com\", \"http://localhost:3000\"]). Use [\"*\"] only for fully public APIs.",
657
753
  "type": "array",
658
754
  "items": {
659
755
  "type": "string"
660
- },
661
- "description": "Allowed CORS origins for browser clients (e.g. [\"https://app.example.com\", \"http://localhost:3000\"]). Use [\"*\"] only for fully public APIs."
756
+ }
662
757
  },
663
758
  "chatEndpoint": {
664
759
  "type": "object",
665
760
  "properties": {
666
761
  "path": {
667
- "type": "string",
668
762
  "default": "/v1/chat",
669
- "description": "URL path for the chat endpoint (e.g. \"/v1/chat\", \"/api/chat\"). Must start with \"/\"."
763
+ "description": "URL path for the chat endpoint (e.g. \"/v1/chat\", \"/api/chat\"). Must start with \"/\".",
764
+ "type": "string"
670
765
  },
671
766
  "protocol": {
767
+ "default": "openai-compatible",
768
+ "description": "\"openai-compatible\" = request/response shape matches the OpenAI Chat Completions API (enables drop-in compatibility with OpenAI SDKs). \"custom\" = proprietary shape defined by the agent.",
672
769
  "type": "string",
673
770
  "enum": [
674
771
  "openai-compatible",
675
772
  "custom"
676
- ],
677
- "default": "openai-compatible",
678
- "description": "\"openai-compatible\" = request/response shape matches the OpenAI Chat Completions API (enables drop-in compatibility with OpenAI SDKs). \"custom\" = proprietary shape defined by the agent."
773
+ ]
679
774
  },
680
775
  "streaming": {
681
- "type": "boolean",
682
776
  "default": true,
683
- "description": "When true, the endpoint supports Server-Sent Events streaming responses. Clients receive tokens as they are generated."
777
+ "description": "When true, the endpoint supports Server-Sent Events streaming responses. Clients receive tokens as they are generated.",
778
+ "type": "boolean"
684
779
  },
685
780
  "sessionMode": {
781
+ "default": "stateful",
782
+ "description": "\"stateful\" = conversation history is persisted per thread (requires threadIdHeader). \"stateless\" = each request is independent; no memory across calls.",
686
783
  "type": "string",
687
784
  "enum": [
688
785
  "stateful",
689
786
  "stateless"
690
- ],
691
- "default": "stateful",
692
- "description": "\"stateful\" = conversation history is persisted per thread (requires threadIdHeader). \"stateless\" = each request is independent; no memory across calls."
787
+ ]
693
788
  },
694
789
  "threadIdHeader": {
695
- "type": "string",
696
790
  "default": "X-Thread-Id",
697
- "description": "HTTP request header used to identify the conversation thread for stateful session routing (e.g. \"X-Thread-Id\", \"X-Session-Id\")."
791
+ "description": "HTTP request header used to identify the conversation thread for stateful session routing (e.g. \"X-Thread-Id\", \"X-Session-Id\").",
792
+ "type": "string"
698
793
  }
699
794
  },
700
795
  "additionalProperties": false
@@ -715,8 +810,8 @@
715
810
  "description": "Skill identifier as registered in the runtime skill registry (e.g. \"code-interpreter\", \"image-gen\")."
716
811
  },
717
812
  "version": {
718
- "type": "string",
719
- "description": "Pinned skill version. Omit to use the latest available version. Semver range or exact version string."
813
+ "description": "Pinned skill version. Omit to use the latest available version. Semver range or exact version string.",
814
+ "type": "string"
720
815
  }
721
816
  },
722
817
  "required": [
@@ -729,6 +824,7 @@
729
824
  "type": "object",
730
825
  "properties": {
731
826
  "input": {
827
+ "description": "Guardrails applied to user input before it is sent to the model. Evaluated in order — first blocking rule wins.",
732
828
  "type": "array",
733
829
  "items": {
734
830
  "anyOf": [
@@ -756,8 +852,8 @@
756
852
  "description": "\"reject\" = refuse the request and return an error, \"warn\" = continue but emit a warning event, \"log\" = silently log the violation."
757
853
  },
758
854
  "message": {
759
- "type": "string",
760
- "description": "Custom error message returned to the user when a topic is blocked. Defaults to a generic refusal message."
855
+ "description": "Custom error message returned to the user when a topic is blocked. Defaults to a generic refusal message.",
856
+ "type": "string"
761
857
  }
762
858
  },
763
859
  "required": [
@@ -784,11 +880,11 @@
784
880
  "description": "\"scrub\" = replace detected PII with placeholders before passing to the model, \"reject\" = refuse the request, \"warn\" = pass through but emit a warning event."
785
881
  },
786
882
  "fields": {
883
+ "description": "Specific PII entity types to detect. When omitted, all PII types supported by the detection library are scanned. Use the same entity names as in spec.memory.hygiene.piiScrubFields.",
787
884
  "type": "array",
788
885
  "items": {
789
886
  "type": "string"
790
- },
791
- "description": "Specific PII entity types to detect. When omitted, all PII types supported by the detection library are scanned. Use the same entity names as in spec.memory.hygiene.piiScrubFields."
887
+ }
792
888
  }
793
889
  },
794
890
  "required": [
@@ -812,13 +908,13 @@
812
908
  ]
813
909
  },
814
910
  "sensitivity": {
911
+ "description": "Detection sensitivity. \"low\" = only block obvious injection patterns, \"medium\" = balanced (default), \"high\" = aggressive — may produce false positives on legitimate complex instructions.",
815
912
  "type": "string",
816
913
  "enum": [
817
914
  "low",
818
915
  "medium",
819
916
  "high"
820
- ],
821
- "description": "Detection sensitivity. \"low\" = only block obvious injection patterns, \"medium\" = balanced (default), \"high\" = aggressive — may produce false positives on legitimate complex instructions."
917
+ ]
822
918
  }
823
919
  },
824
920
  "required": [
@@ -863,10 +959,10 @@
863
959
  "discriminator": {
864
960
  "propertyName": "type"
865
961
  }
866
- },
867
- "description": "Guardrails applied to user input before it is sent to the model. Evaluated in order — first blocking rule wins."
962
+ }
868
963
  },
869
964
  "output": {
965
+ "description": "Guardrails applied to model output before it is returned to the user. Evaluated in order — first blocking rule wins.",
870
966
  "type": "array",
871
967
  "items": {
872
968
  "anyOf": [
@@ -893,10 +989,10 @@
893
989
  "description": "\"reject\" = return error to user, \"retry\" = re-invoke the model (up to maxRetries), \"warn\" = return response with a warning annotation."
894
990
  },
895
991
  "maxRetries": {
992
+ "description": "Maximum re-generation attempts before giving up. Only used when action is \"retry\". Defaults to 1.",
896
993
  "type": "integer",
897
994
  "minimum": 1,
898
- "maximum": 5,
899
- "description": "Maximum re-generation attempts before giving up. Only used when action is \"retry\". Defaults to 1."
995
+ "maximum": 5
900
996
  }
901
997
  },
902
998
  "required": [
@@ -951,11 +1047,11 @@
951
1047
  "description": "\"scrub\" = replace PII in the model output before returning to the user, \"reject\" = discard the response and return an error, \"warn\" = return with a warning annotation."
952
1048
  },
953
1049
  "fields": {
1050
+ "description": "Specific PII entity types to detect in model output. Omit to scan all types. Use the same entity names as in spec.memory.hygiene.piiScrubFields.",
954
1051
  "type": "array",
955
1052
  "items": {
956
1053
  "type": "string"
957
- },
958
- "description": "Specific PII entity types to detect in model output. Omit to scan all types. Use the same entity names as in spec.memory.hygiene.piiScrubFields."
1054
+ }
959
1055
  }
960
1056
  },
961
1057
  "required": [
@@ -1000,8 +1096,7 @@
1000
1096
  "discriminator": {
1001
1097
  "propertyName": "type"
1002
1098
  }
1003
- },
1004
- "description": "Guardrails applied to model output before it is returned to the user. Evaluated in order — first blocking rule wins."
1099
+ }
1005
1100
  }
1006
1101
  },
1007
1102
  "additionalProperties": false
@@ -1010,10 +1105,11 @@
1010
1105
  "type": "object",
1011
1106
  "properties": {
1012
1107
  "enabled": {
1013
- "type": "boolean",
1014
- "default": false
1108
+ "default": false,
1109
+ "type": "boolean"
1015
1110
  },
1016
1111
  "approvalRequired": {
1112
+ "description": "Conditions that pause execution and request human approval. \"before-destructive-tool\" = any tool with destructiveHint=true, \"on-low-confidence\" = model confidence below a threshold, \"on-high-cost\" = single call exceeds cost controls.",
1017
1113
  "type": "array",
1018
1114
  "items": {
1019
1115
  "type": "string",
@@ -1024,27 +1120,27 @@
1024
1120
  "on-high-cost",
1025
1121
  "always"
1026
1122
  ]
1027
- },
1028
- "description": "Conditions that pause execution and request human approval. \"before-destructive-tool\" = any tool with destructiveHint=true, \"on-low-confidence\" = model confidence below a threshold, \"on-high-cost\" = single call exceeds cost controls."
1123
+ }
1029
1124
  },
1030
1125
  "timeoutSeconds": {
1126
+ "default": 300,
1127
+ "description": "Seconds to wait for human approval before executing the timeoutAction. Default 300s (5 minutes). Max 3600s (1 hour).",
1031
1128
  "type": "integer",
1032
1129
  "minimum": 1,
1033
- "maximum": 3600,
1034
- "default": 300,
1035
- "description": "Seconds to wait for human approval before executing the timeoutAction. Default 300s (5 minutes). Max 3600s (1 hour)."
1130
+ "maximum": 3600
1036
1131
  },
1037
1132
  "timeoutAction": {
1133
+ "default": "reject",
1134
+ "description": "\"reject\" = abort the action and return an error (default, safest), \"proceed\" = continue without approval (use only for low-risk actions), \"escalate\" = forward to a higher-level approver or on-call channel.",
1038
1135
  "type": "string",
1039
1136
  "enum": [
1040
1137
  "reject",
1041
1138
  "proceed",
1042
1139
  "escalate"
1043
- ],
1044
- "default": "reject",
1045
- "description": "\"reject\" = abort the action and return an error (default, safest), \"proceed\" = continue without approval (use only for low-risk actions), \"escalate\" = forward to a higher-level approver or on-call channel."
1140
+ ]
1046
1141
  },
1047
1142
  "notifyVia": {
1143
+ "description": "Channels used to notify humans when approval is required. Multiple channels can be specified; all are notified simultaneously.",
1048
1144
  "type": "array",
1049
1145
  "items": {
1050
1146
  "type": "string",
@@ -1054,12 +1150,11 @@
1054
1150
  "webhook",
1055
1151
  "console"
1056
1152
  ]
1057
- },
1058
- "description": "Channels used to notify humans when approval is required. Multiple channels can be specified; all are notified simultaneously."
1153
+ }
1059
1154
  },
1060
1155
  "webhookUrl": {
1061
- "type": "string",
1062
- "description": "URL to POST approval requests to when notifyVia includes \"webhook\". The payload contains the pending action and a callback token. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
1156
+ "description": "URL to POST approval requests to when notifyVia includes \"webhook\". The payload contains the pending action and a callback token. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
1157
+ "type": "string"
1063
1158
  }
1064
1159
  },
1065
1160
  "additionalProperties": false
@@ -1068,6 +1163,7 @@
1068
1163
  "type": "object",
1069
1164
  "properties": {
1070
1165
  "framework": {
1166
+ "description": "Deprecated: nothing reads it. validate warns when set; rejected in 0.6.0.",
1071
1167
  "type": "string",
1072
1168
  "enum": [
1073
1169
  "deepeval",
@@ -1077,7 +1173,82 @@
1077
1173
  "custom"
1078
1174
  ]
1079
1175
  },
1176
+ "live": {
1177
+ "description": "Live evaluation, separate from dataset evaluation. Only live metrics are allowed.",
1178
+ "type": "object",
1179
+ "properties": {
1180
+ "metrics": {
1181
+ "description": "Metrics scored on live traffic.",
1182
+ "type": "array",
1183
+ "items": {
1184
+ "type": "string",
1185
+ "enum": [
1186
+ "faithfulness",
1187
+ "answer_relevancy",
1188
+ "hallucination",
1189
+ "toxicity",
1190
+ "context_precision",
1191
+ "bias",
1192
+ "grounded",
1193
+ "pii_leakage",
1194
+ "prompt_injection",
1195
+ "custom"
1196
+ ]
1197
+ }
1198
+ },
1199
+ "thresholds": {
1200
+ "description": "Minimum pass rate per live metric (0.0–1.0).",
1201
+ "type": "object",
1202
+ "additionalProperties": {
1203
+ "type": "number",
1204
+ "minimum": 0,
1205
+ "maximum": 1
1206
+ }
1207
+ },
1208
+ "custom": {
1209
+ "type": "object",
1210
+ "properties": {
1211
+ "name": {
1212
+ "type": "string",
1213
+ "minLength": 1,
1214
+ "description": "Name the custom metric is reported under."
1215
+ },
1216
+ "rubric": {
1217
+ "type": "string",
1218
+ "description": "Grading rubric. Use \"$file:rubrics/<name>.md\"; the loader resolves it to the file contents."
1219
+ }
1220
+ },
1221
+ "required": [
1222
+ "name",
1223
+ "rubric"
1224
+ ],
1225
+ "additionalProperties": false
1226
+ }
1227
+ },
1228
+ "additionalProperties": false
1229
+ },
1230
+ "custom": {
1231
+ "description": "Rubric for the \"custom\" metric on datasets.",
1232
+ "type": "object",
1233
+ "properties": {
1234
+ "name": {
1235
+ "type": "string",
1236
+ "minLength": 1,
1237
+ "description": "Name the custom metric is reported under."
1238
+ },
1239
+ "rubric": {
1240
+ "type": "string",
1241
+ "description": "Grading rubric. Use \"$file:rubrics/<name>.md\"; the loader resolves it to the file contents."
1242
+ }
1243
+ },
1244
+ "required": [
1245
+ "name",
1246
+ "rubric"
1247
+ ],
1248
+ "additionalProperties": false
1249
+ },
1080
1250
  "datasets": {
1251
+ "description": "Evaluation datasets. Each entry maps a name to a JSONL file and optionally scopes which metrics to compute.",
1081
1252
  "type": "array",
1082
1253
  "items": {
1083
1254
  "type": "object",
@@ -1088,9 +1259,10 @@
1088
1259
  },
1089
1260
  "path": {
1090
1261
  "type": "string",
1091
- "description": "Path to the evaluation dataset file (JSONL format). Use \"$file:evals/my_dataset.jsonl\" syntax. Each line is a JSON object with the following fields:\n input (required) – user query sent to the agent.\n expected (required) – expected output; used for string_match and answer_similarity scoring.\n context (optional) – string[] of retrieved chunks the agent actually used. Required for faithfulness, context_precision, hallucination metrics.\n reference_contexts (optional) – string[] of ground-truth relevant chunks. Required for context_recall metric.\n tags (optional) – string[] labels for filtering with --tag.\n metadata (optional) – arbitrary key/value pairs for reporting (e.g. {\"difficulty\": \"hard\"}).\nExample: {\"input\":\"What is RAG?\",\"expected\":\"Retrieval Augmented Generation\",\"context\":[\"RAG combines retrieval...\"],\"tags\":[\"rag\"]}"
1262
+ "description": "Path to the evaluation dataset file (JSONL format). Use \"$file:evals/my_dataset.jsonl\" syntax. Each line is a JSON object with the following fields:\n input (required) – user query sent to the agent.\n expected (required) – expected output; used for string_match and answer_similarity scoring.\n context (optional) – string[] of retrieved chunks the agent actually used. Required for grounded and context_precision metrics.\n reference_contexts (optional) – string[] of ground-truth relevant chunks. Required for context_recall metric.\n tags (optional) – string[] labels for filtering with --tag.\n metadata (optional) – arbitrary key/value pairs for reporting (e.g. {\"difficulty\": \"hard\"}).\nExample: {\"input\":\"What is RAG?\",\"expected\":\"Retrieval Augmented Generation\",\"context\":[\"RAG combines retrieval...\"],\"tags\":[\"rag\"]}"
1092
1263
  },
1093
1264
  "metrics": {
1265
+ "description": "Metrics to compute for this specific dataset. Overrides (narrows) spec.evaluation.metrics for this dataset only. When omitted, the global spec.evaluation.metrics list is used. Example: a RAG dataset sets [\"grounded\",\"context_recall\"] while a safety dataset sets [\"toxicity\",\"bias\"].",
1094
1266
  "type": "array",
1095
1267
  "items": {
1096
1268
  "type": "string",
@@ -1103,10 +1275,12 @@
1103
1275
  "context_precision",
1104
1276
  "context_recall",
1105
1277
  "bias",
1278
+ "grounded",
1279
+ "pii_leakage",
1280
+ "prompt_injection",
1106
1281
  "custom"
1107
1282
  ]
1108
- },
1109
- "description": "Metrics to compute for this specific dataset. Overrides (narrows) spec.evaluation.metrics for this dataset only. When omitted, the global spec.evaluation.metrics list is used. Example: a RAG dataset sets [\"faithfulness\",\"context_recall\"] while a safety dataset sets [\"toxicity\",\"bias\"]."
1283
+ }
1110
1284
  }
1111
1285
  },
1112
1286
  "required": [
@@ -1114,10 +1288,10 @@
1114
1288
  "path"
1115
1289
  ],
1116
1290
  "additionalProperties": false
1117
- },
1118
- "description": "Evaluation datasets. Each entry maps a name to a JSONL file and optionally scopes which metrics to compute."
1291
+ }
1119
1292
  },
1120
1293
  "metrics": {
1294
+ "description": "Default metrics to compute across all datasets that do not declare their own metrics. \"grounded\", \"context_precision\", \"context_recall\" require the \"context\" field in dataset samples. \"context_recall\" additionally requires \"reference_contexts\". \"custom\" requires spec.evaluation.custom: { name, rubric }. \"faithfulness\" and \"hallucination\" are deprecated aliases of \"grounded\".",
1121
1295
  "type": "array",
1122
1296
  "items": {
1123
1297
  "type": "string",
@@ -1130,29 +1304,28 @@
1130
1304
  "context_precision",
1131
1305
  "context_recall",
1132
1306
  "bias",
1307
+ "grounded",
1308
+ "pii_leakage",
1309
+ "prompt_injection",
1133
1310
  "custom"
1134
1311
  ]
1135
- },
1136
- "description": "Default metrics to compute across all datasets that do not declare their own metrics. \"faithfulness\", \"context_precision\", \"context_recall\" require the \"context\" field in dataset samples. \"context_recall\" additionally requires \"reference_contexts\". \"custom\" requires a scorer registered in the evaluation framework config."
1312
+ }
1137
1313
  },
1138
1314
  "thresholds": {
1315
+ "description": "Pass/fail thresholds per metric (0.0–1.0). Key = metric name, value = minimum required score. Example: {\"grounded\": 0.95, \"answer_relevancy\": 0.75}. Used by ciGate and \"agentspec evaluate\".",
1139
1316
  "type": "object",
1140
1317
  "additionalProperties": {
1141
1318
  "type": "number",
1142
1319
  "minimum": 0,
1143
1320
  "maximum": 1
1144
- },
1145
- "description": "Pass/fail thresholds per metric (0.0–1.0). Key = metric name, value = minimum required score. Example: {\"faithfulness\": 0.8, \"answer_relevancy\": 0.75}. Used by ciGate and \"agentspec evaluate\"."
1321
+ }
1146
1322
  },
1147
1323
  "ciGate": {
1148
- "type": "boolean",
1149
1324
  "default": false,
1150
- "description": "When true, \"agentspec evaluate\" exits with code 1 if any metric falls below its threshold. Blocks CI pipelines on evaluation regression (EVAL-01)."
1325
+ "description": "When true, \"agentspec evaluate\" exits with code 1 if any metric falls below its threshold. Blocks CI pipelines on evaluation regression (EVAL-01).",
1326
+ "type": "boolean"
1151
1327
  }
1152
1328
  },
1153
- "required": [
1154
- "framework"
1155
- ],
1156
1329
  "additionalProperties": false
1157
1330
  },
1158
1331
  "observability": {
@@ -1173,23 +1346,23 @@
1173
1346
  ]
1174
1347
  },
1175
1348
  "endpoint": {
1176
- "type": "string",
1177
- "description": "Tracing collector endpoint URL. Required for \"otel\", \"honeycomb\", and self-hosted backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
1349
+ "description": "Tracing collector endpoint URL. Required for \"otel\", \"honeycomb\", and self-hosted backends. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
1350
+ "type": "string"
1178
1351
  },
1179
1352
  "publicKey": {
1180
- "type": "string",
1181
- "description": "Public/project API key for the tracing backend (e.g. Langfuse public key). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
1353
+ "description": "Public/project API key for the tracing backend (e.g. Langfuse public key). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
1354
+ "type": "string"
1182
1355
  },
1183
1356
  "secretKey": {
1184
- "type": "string",
1185
- "description": "Secret API key for the tracing backend (e.g. Langfuse secret key). Always use \"$secret:\" or \"$env:\" — never hardcode. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
1357
+ "description": "Secret API key for the tracing backend (e.g. Langfuse secret key). Always use \"$secret:\" or \"$env:\" — never hardcode. Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
1358
+ "type": "string"
1186
1359
  },
1187
1360
  "sampleRate": {
1361
+ "default": 1,
1362
+ "description": "Fraction of requests to trace (0.0–1.0). 1.0 = trace every request (default), 0.1 = trace 10% for high-traffic cost savings. Set to 1.0 during development.",
1188
1363
  "type": "number",
1189
1364
  "minimum": 0,
1190
- "maximum": 1,
1191
- "default": 1,
1192
- "description": "Fraction of requests to trace (0.0–1.0). 1.0 = trace every request (default), 0.1 = trace 10% for high-traffic cost savings. Set to 1.0 during development."
1365
+ "maximum": 1
1193
1366
  }
1194
1367
  },
1195
1368
  "required": [
@@ -1209,12 +1382,12 @@
1209
1382
  ]
1210
1383
  },
1211
1384
  "endpoint": {
1212
- "type": "string",
1213
- "description": "Metrics export endpoint (e.g. OTLP endpoint for OpenTelemetry, Datadog agent URL). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value."
1385
+ "description": "Metrics export endpoint (e.g. OTLP endpoint for OpenTelemetry, Datadog agent URL). Supports reference syntax: \"$env:VAR_NAME\" (env var), \"$secret:name\" (secret manager), \"$file:path\" (file relative to agent.yaml), or a literal string value.",
1386
+ "type": "string"
1214
1387
  },
1215
1388
  "serviceName": {
1216
- "type": "string",
1217
- "description": "Service name used to label all emitted metrics and traces. Defaults to metadata.name. Use a consistent name across deployments for accurate dashboards."
1389
+ "description": "Service name used to label all emitted metrics and traces. Defaults to metadata.name. Use a consistent name across deployments for accurate dashboards.",
1390
+ "type": "string"
1218
1391
  }
1219
1392
  },
1220
1393
  "required": [
@@ -1226,26 +1399,26 @@
1226
1399
  "type": "object",
1227
1400
  "properties": {
1228
1401
  "level": {
1402
+ "default": "info",
1229
1403
  "type": "string",
1230
1404
  "enum": [
1231
1405
  "debug",
1232
1406
  "info",
1233
1407
  "warn",
1234
1408
  "error"
1235
- ],
1236
- "default": "info"
1409
+ ]
1237
1410
  },
1238
1411
  "structured": {
1239
- "type": "boolean",
1240
1412
  "default": true,
1241
- "description": "When true, logs are emitted as JSON objects (structured logging). Required for log aggregation platforms (Datadog, Splunk, CloudWatch). Set false only for local development readability."
1413
+ "description": "When true, logs are emitted as JSON objects (structured logging). Required for log aggregation platforms (Datadog, Splunk, CloudWatch). Set false only for local development readability.",
1414
+ "type": "boolean"
1242
1415
  },
1243
1416
  "redactFields": {
1417
+ "description": "Field names to redact from structured log output before writing to log sinks. Use the same values as spec.memory.hygiene.piiScrubFields plus any application-specific sensitive keys (e.g. [\"password\", \"credit_card\", \"session_token\"]).",
1244
1418
  "type": "array",
1245
1419
  "items": {
1246
1420
  "type": "string"
1247
- },
1248
- "description": "Field names to redact from structured log output before writing to log sinks. Use the same values as spec.memory.hygiene.piiScrubFields plus any application-specific sensitive keys (e.g. [\"password\", \"credit_card\", \"session_token\"])."
1421
+ }
1249
1422
  }
1250
1423
  },
1251
1424
  "additionalProperties": false
@@ -1257,6 +1430,7 @@
1257
1430
  "type": "object",
1258
1431
  "properties": {
1259
1432
  "packs": {
1433
+ "description": "Compliance rule packs to evaluate during \"agentspec audit\". Each pack groups related rules. Omit to run all packs.",
1260
1434
  "type": "array",
1261
1435
  "items": {
1262
1436
  "type": "string",
@@ -1265,12 +1439,13 @@
1265
1439
  "memory-hygiene",
1266
1440
  "model-resilience",
1267
1441
  "evaluation-coverage",
1268
- "observability"
1442
+ "observability",
1443
+ "metadata-quality"
1269
1444
  ]
1270
- },
1271
- "description": "Compliance rule packs to evaluate during \"agentspec audit\". Each pack groups related rules. Omit to run all packs."
1445
+ }
1272
1446
  },
1273
1447
  "suppressions": {
1448
+ "description": "Rules to suppress in audit output. Each suppression requires a reason and optional expiry date. Over-suppression is itself flagged.",
1274
1449
  "type": "array",
1275
1450
  "items": {
1276
1451
  "type": "object",
@@ -1284,12 +1459,12 @@
1284
1459
  "description": "Human-readable justification for suppressing this rule. Required for audit trails. Example: \"Hallucination detection handled by external Lakera Guard proxy.\""
1285
1460
  },
1286
1461
  "approvedBy": {
1287
- "type": "string",
1288
- "description": "Name or identifier of the person who approved this suppression (e.g. \"security-team\", \"alice@example.com\"). Used for compliance sign-off tracking."
1462
+ "description": "Name or identifier of the person who approved this suppression (e.g. \"security-team\", \"alice@example.com\"). Used for compliance sign-off tracking.",
1463
+ "type": "string"
1289
1464
  },
1290
1465
  "expires": {
1291
- "type": "string",
1292
- "description": "ISO 8601 date (YYYY-MM-DD) when this suppression expires and should be re-evaluated (e.g. \"2025-12-31\"). Suppressions without an expiry are flagged in audits."
1466
+ "description": "ISO 8601 date (YYYY-MM-DD) when this suppression expires and should be re-evaluated (e.g. \"2025-12-31\"). Suppressions without an expiry are flagged in audits.",
1467
+ "type": "string"
1293
1468
  }
1294
1469
  },
1295
1470
  "required": [
@@ -1297,18 +1472,17 @@
1297
1472
  "reason"
1298
1473
  ],
1299
1474
  "additionalProperties": false
1300
- },
1301
- "description": "Rules to suppress in audit output. Each suppression requires a reason and optional expiry date. Over-suppression is itself flagged."
1475
+ }
1302
1476
  },
1303
1477
  "auditSchedule": {
1478
+ "description": "How often the compliance audit should be re-run in CI. \"on-change\" = re-audit on every manifest change (recommended). Informational — enforcement depends on your CI configuration.",
1304
1479
  "type": "string",
1305
1480
  "enum": [
1306
1481
  "daily",
1307
1482
  "weekly",
1308
1483
  "monthly",
1309
1484
  "on-change"
1310
- ],
1311
- "description": "How often the compliance audit should be re-run in CI. \"on-change\" = re-audit on every manifest change (recommended). Informational — enforcement depends on your CI configuration."
1485
+ ]
1312
1486
  }
1313
1487
  },
1314
1488
  "additionalProperties": false
@@ -1317,13 +1491,14 @@
1317
1491
  "type": "object",
1318
1492
  "properties": {
1319
1493
  "envVars": {
1494
+ "description": "Environment variable names that must be set at agent startup. The SDK validates these at load time and throws a descriptive error if any are missing (e.g. [\"OPENAI_API_KEY\", \"DATABASE_URL\"]).",
1320
1495
  "type": "array",
1321
1496
  "items": {
1322
1497
  "type": "string"
1323
- },
1324
- "description": "Environment variable names that must be set at agent startup. The SDK validates these at load time and throws a descriptive error if any are missing (e.g. [\"OPENAI_API_KEY\", \"DATABASE_URL\"])."
1498
+ }
1325
1499
  },
1326
1500
  "services": {
1501
+ "description": "External services that must be reachable at startup. The SDK health check verifies TCP connectivity to each service.",
1327
1502
  "type": "array",
1328
1503
  "items": {
1329
1504
  "type": "object",
@@ -1348,21 +1523,20 @@
1348
1523
  "connection"
1349
1524
  ],
1350
1525
  "additionalProperties": false
1351
- },
1352
- "description": "External services that must be reachable at startup. The SDK health check verifies TCP connectivity to each service."
1526
+ }
1353
1527
  },
1354
1528
  "minimumMemoryMB": {
1529
+ "description": "Minimum RAM required to run the agent in megabytes (e.g. 512, 2048). Used by orchestrators for resource scheduling. Does not enforce a limit — purely declarative.",
1355
1530
  "type": "integer",
1356
- "minimum": 128,
1357
- "description": "Minimum RAM required to run the agent in megabytes (e.g. 512, 2048). Used by orchestrators for resource scheduling. Does not enforce a limit — purely declarative."
1531
+ "minimum": 128
1358
1532
  },
1359
1533
  "nodeVersion": {
1360
- "type": "string",
1361
- "description": "Minimum Node.js version required, as a semver range or exact version (e.g. \">=20.0.0\", \"20.x\"). Used by CI and orchestrators for compatibility checks."
1534
+ "description": "Minimum Node.js version required, as a semver range or exact version (e.g. \">=20.0.0\", \"20.x\"). Used by CI and orchestrators for compatibility checks.",
1535
+ "type": "string"
1362
1536
  },
1363
1537
  "pythonVersion": {
1364
- "type": "string",
1365
- "description": "Minimum Python version required, as a semver range or exact version (e.g. \">=3.11\", \"3.12\"). Used by CI and orchestrators for compatibility checks."
1538
+ "description": "Minimum Python version required, as a semver range or exact version (e.g. \">=3.11\", \"3.12\"). Used by CI and orchestrators for compatibility checks.",
1539
+ "type": "string"
1366
1540
  }
1367
1541
  },
1368
1542
  "additionalProperties": false