@openlucaskaka/kagent 0.1.7

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 (117) hide show
  1. package/README.md +353 -0
  2. package/npm/bin/kagent-serve.js +6 -0
  3. package/npm/bin/kagent.js +6 -0
  4. package/npm/lib/App.js +524 -0
  5. package/npm/lib/app-state.js +224 -0
  6. package/npm/lib/approval-choice.js +25 -0
  7. package/npm/lib/commands.js +59 -0
  8. package/npm/lib/editor.js +188 -0
  9. package/npm/lib/ink-runner.js +41 -0
  10. package/npm/lib/kagent-home.js +39 -0
  11. package/npm/lib/launcher.js +221 -0
  12. package/npm/lib/protocol.js +33 -0
  13. package/npm/lib/provider-setup.js +139 -0
  14. package/npm/lib/python-runner.js +892 -0
  15. package/npm/lib/runtime-client.js +390 -0
  16. package/npm/lib/terminal-input.js +127 -0
  17. package/npm/lib/terminal-text.js +19 -0
  18. package/npm/lib/terminal-width.js +14 -0
  19. package/npm/lib/transcript.js +227 -0
  20. package/npm/lib/ui-components.js +247 -0
  21. package/npm/lib/update-manager.js +334 -0
  22. package/package.json +39 -0
  23. package/pyproject.toml +55 -0
  24. package/src/kagent/__init__.py +90 -0
  25. package/src/kagent/cli/__init__.py +5 -0
  26. package/src/kagent/cli/__main__.py +6 -0
  27. package/src/kagent/cli/commands.py +112 -0
  28. package/src/kagent/cli/conversation.py +127 -0
  29. package/src/kagent/cli/interactive.py +841 -0
  30. package/src/kagent/cli/main.py +685 -0
  31. package/src/kagent/cli/memory.py +460 -0
  32. package/src/kagent/cli/pending_approval.py +169 -0
  33. package/src/kagent/cli/provider.py +27 -0
  34. package/src/kagent/cli/session_commands.py +401 -0
  35. package/src/kagent/cli/stdio_runtime.py +784 -0
  36. package/src/kagent/cli/trace.py +67 -0
  37. package/src/kagent/cli/ui.py +931 -0
  38. package/src/kagent/core/__init__.py +0 -0
  39. package/src/kagent/core/agent.py +296 -0
  40. package/src/kagent/core/faults.py +11 -0
  41. package/src/kagent/core/invariants.py +47 -0
  42. package/src/kagent/core/normalization.py +81 -0
  43. package/src/kagent/core/planning.py +48 -0
  44. package/src/kagent/core/state.py +73 -0
  45. package/src/kagent/core/summary.py +64 -0
  46. package/src/kagent/core/tools.py +196 -0
  47. package/src/kagent/core/trace.py +57 -0
  48. package/src/kagent/eval/__init__.py +11 -0
  49. package/src/kagent/eval/cases.py +229 -0
  50. package/src/kagent/eval/evaluator.py +216 -0
  51. package/src/kagent/integrations/__init__.py +3 -0
  52. package/src/kagent/integrations/audit.py +95 -0
  53. package/src/kagent/integrations/backends.py +131 -0
  54. package/src/kagent/integrations/memory.py +301 -0
  55. package/src/kagent/ops/__init__.py +0 -0
  56. package/src/kagent/ops/batch.py +156 -0
  57. package/src/kagent/ops/doctor.py +255 -0
  58. package/src/kagent/ops/metrics.py +214 -0
  59. package/src/kagent/ops/release_evidence.py +877 -0
  60. package/src/kagent/ops/release_manifest.py +142 -0
  61. package/src/kagent/ops/trace_replay.py +285 -0
  62. package/src/kagent/providers/__init__.py +7 -0
  63. package/src/kagent/providers/embeddings.py +187 -0
  64. package/src/kagent/providers/llm.py +770 -0
  65. package/src/kagent/py.typed +1 -0
  66. package/src/kagent/runtime/__init__.py +28 -0
  67. package/src/kagent/runtime/action_graph.py +543 -0
  68. package/src/kagent/runtime/agent.py +2089 -0
  69. package/src/kagent/runtime/approval.py +64 -0
  70. package/src/kagent/runtime/cancellation.py +64 -0
  71. package/src/kagent/runtime/checkpoint_state.py +146 -0
  72. package/src/kagent/runtime/checkpoint_storage.py +270 -0
  73. package/src/kagent/runtime/context.py +65 -0
  74. package/src/kagent/runtime/file_transaction.py +195 -0
  75. package/src/kagent/runtime/hooks.py +74 -0
  76. package/src/kagent/runtime/metadata.py +116 -0
  77. package/src/kagent/runtime/patch_checkpoints.py +385 -0
  78. package/src/kagent/runtime/policy.py +50 -0
  79. package/src/kagent/runtime/presentation.py +205 -0
  80. package/src/kagent/runtime/redaction.py +130 -0
  81. package/src/kagent/runtime/sandbox.py +331 -0
  82. package/src/kagent/runtime/skills.py +66 -0
  83. package/src/kagent/runtime/steering.py +56 -0
  84. package/src/kagent/runtime/steps.py +255 -0
  85. package/src/kagent/runtime/task_state.py +40 -0
  86. package/src/kagent/runtime/tools.py +3532 -0
  87. package/src/kagent/runtime/types.py +240 -0
  88. package/src/kagent/runtime/workspace.py +597 -0
  89. package/src/kagent/service/__init__.py +26 -0
  90. package/src/kagent/service/__main__.py +6 -0
  91. package/src/kagent/service/active_runs.py +178 -0
  92. package/src/kagent/service/cli.py +737 -0
  93. package/src/kagent/service/contract.py +2571 -0
  94. package/src/kagent/service/errors.py +71 -0
  95. package/src/kagent/service/idempotency.py +584 -0
  96. package/src/kagent/service/router.py +884 -0
  97. package/src/kagent/service/run.py +150 -0
  98. package/src/kagent/service/runtime.py +1915 -0
  99. package/src/kagent/service/runtime_approval.py +20 -0
  100. package/src/kagent/service/runtime_cancel.py +192 -0
  101. package/src/kagent/service/runtime_lifecycle.py +229 -0
  102. package/src/kagent/service/runtime_metadata.py +21 -0
  103. package/src/kagent/service/runtime_policy.py +115 -0
  104. package/src/kagent/service/runtime_recovery.py +573 -0
  105. package/src/kagent/service/runtime_resume.py +382 -0
  106. package/src/kagent/service/runtime_resume_claim.py +116 -0
  107. package/src/kagent/service/runtime_run.py +350 -0
  108. package/src/kagent/service/runtime_status.py +2007 -0
  109. package/src/kagent/service/safety.py +139 -0
  110. package/src/kagent/service/server.py +114 -0
  111. package/src/kagent/service/status.py +233 -0
  112. package/src/kagent/service/trace_store.py +322 -0
  113. package/src/kagent/service/transport.py +24 -0
  114. package/src/kagent/utils/__init__.py +0 -0
  115. package/src/kagent/utils/config_validation.py +21 -0
  116. package/src/kagent/utils/json_output.py +23 -0
  117. package/src/kagent/utils/paths.py +473 -0
package/src/kagent/service/contract.py ADDED
@@ -0,0 +1,2571 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Dict, Optional
4
+
5
+ from kagent.runtime import RUNTIME_TRACE_TYPE
6
+ from kagent.service.errors import ERROR_CODES, READINESS_FAILED
7
+
8
+ ALLOWED_HTTP_METHODS = "GET, HEAD, OPTIONS, POST"
9
+ COMMON_RESPONSE_HEADERS = {
10
+ "X-Request-ID": {
11
+ "description": "Request correlation identifier echoed or generated by the service",
12
+ "schema": {"type": "string"},
13
+ },
14
+ "X-Content-Type-Options": {
15
+ "description": "Content sniffing protection",
16
+ "schema": {"type": "string", "const": "nosniff"},
17
+ },
18
+ "Cache-Control": {
19
+ "description": "Disable client and intermediary response caching",
20
+ "schema": {"type": "string", "const": "no-store"},
21
+ },
22
+ "Referrer-Policy": {
23
+ "description": "Prevent referrer leakage from browser or proxy contexts",
24
+ "schema": {"type": "string", "const": "no-referrer"},
25
+ },
26
+ "Content-Security-Policy": {
27
+ "description": "Disable browser-executed content and framing for API responses",
28
+ "schema": {
29
+ "type": "string",
30
+ "const": "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
31
+ },
32
+ },
33
+ "X-Frame-Options": {
34
+ "description": "Deny legacy browser framing of API responses",
35
+ "schema": {"type": "string", "const": "DENY"},
36
+ },
37
+ }
38
+
39
+
40
+ def service_openapi() -> Dict[str, Any]:
41
+ return {
42
+ "openapi": "3.1.0",
43
+ "info": {
44
+ "title": "kagent API",
45
+ "version": "0.1.7",
46
+ },
47
+ "components": {
48
+ "securitySchemes": {
49
+ "BearerAuth": {
50
+ "type": "http",
51
+ "scheme": "bearer",
52
+ }
53
+ },
54
+ "schemas": {
55
+ "HealthResponse": {
56
+ "type": "object",
57
+ "required": ["status"],
58
+ "properties": {
59
+ "status": {"type": "string", "const": "ok"},
60
+ },
61
+ },
62
+ "ReadinessResponse": {
63
+ "type": "object",
64
+ "required": ["status", "checks", "failed_checks"],
65
+ "properties": {
66
+ "status": {"type": "string", "enum": ["ready", "not_ready"]},
67
+ "checks": {
68
+ "type": "object",
69
+ "additionalProperties": {"type": "string"},
70
+ },
71
+ "error_code": {"type": "string", "const": READINESS_FAILED},
72
+ "failed_checks": {
73
+ "type": "array",
74
+ "items": {"type": "string"},
75
+ },
76
+ },
77
+ },
78
+ "ConfigResponse": {
79
+ "type": "object",
80
+ "properties": _diagnostic_audit_properties(),
81
+ "additionalProperties": {"type": "string"},
82
+ },
83
+ "VersionResponse": {
84
+ "type": "object",
85
+ "required": ["version"],
86
+ "properties": {
87
+ "version": {"type": "string"},
88
+ },
89
+ },
90
+ "ToolsResponse": {
91
+ "type": "object",
92
+ "required": ["tools"],
93
+ "properties": {
94
+ "tools": {
95
+ "type": "array",
96
+ "items": {"type": "object"},
97
+ },
98
+ },
99
+ },
100
+ "RuntimeGraphResponse": {
101
+ "type": "object",
102
+ "required": [
103
+ "runtime_engine",
104
+ "entry_point",
105
+ "terminal",
106
+ "nodes",
107
+ "edges",
108
+ "loop",
109
+ "runtime_loop_nodes",
110
+ "execution_flow",
111
+ ],
112
+ "properties": {
113
+ "runtime_engine": {"type": "string", "enum": ["langgraph"]},
114
+ "entry_point": {"type": "string"},
115
+ "terminal": {"type": "string"},
116
+ "nodes": {"type": "array", "items": {"type": "string"}},
117
+ "edges": {"type": "array", "items": {"type": "string"}},
118
+ "loop": {"type": "string"},
119
+ "runtime_loop_nodes": {
120
+ "type": "array",
121
+ "items": {"type": "string"},
122
+ },
123
+ "execution_flow": {
124
+ "type": "array",
125
+ "items": {"type": "string"},
126
+ },
127
+ },
128
+ "additionalProperties": False,
129
+ },
130
+ "RuntimeToolsResponse": {
131
+ "type": "object",
132
+ "required": ["tools"],
133
+ "properties": {
134
+ "tools": {
135
+ "type": "array",
136
+ "items": {"$ref": "#/components/schemas/RuntimeToolMetadata"},
137
+ },
138
+ },
139
+ },
140
+ "RuntimeToolMetadata": {
141
+ "type": "object",
142
+ "required": [
143
+ "name",
144
+ "description",
145
+ "approval_required_by_default",
146
+ "input_schema",
147
+ "output_schema",
148
+ "timeout_seconds",
149
+ ],
150
+ "properties": {
151
+ "name": {"type": "string"},
152
+ "description": {"type": "string"},
153
+ "approval_required_by_default": {
154
+ "type": "string",
155
+ "enum": ["true", "false"],
156
+ },
157
+ "input_schema": {"type": "object"},
158
+ "output_schema": {"type": "object"},
159
+ "timeout_seconds": {
160
+ "type": "string",
161
+ "pattern": r"^\d+\.\d$",
162
+ },
163
+ },
164
+ "additionalProperties": False,
165
+ },
166
+ "RuntimeGraphPhase": {
167
+ "type": "object",
168
+ "required": [
169
+ "node",
170
+ "status",
171
+ "started_at",
172
+ "completed_at",
173
+ "duration_seconds",
174
+ ],
175
+ "properties": {
176
+ "node": {"type": "string"},
177
+ "status": {"type": "string", "enum": ["ok", "failed"]},
178
+ "started_at": {"type": "string"},
179
+ "completed_at": {"type": "string"},
180
+ "duration_seconds": {
181
+ "type": "string",
182
+ "pattern": r"^\d+\.\d{4}$",
183
+ },
184
+ },
185
+ "additionalProperties": False,
186
+ },
187
+ "MetricsResponse": {
188
+ "type": "object",
189
+ "properties": _metrics_response_properties(),
190
+ "additionalProperties": {
191
+ "oneOf": [
192
+ {"type": "string"},
193
+ {
194
+ "type": "object",
195
+ "additionalProperties": {"type": "string"},
196
+ },
197
+ ]
198
+ },
199
+ },
200
+ "RunRequest": {
201
+ "type": "object",
202
+ "required": ["goal"],
203
+ "properties": {
204
+ "goal": {"type": "string", "maxLength": 4096},
205
+ "max_steps": {"type": "integer", "minimum": 1},
206
+ "max_retries": {"type": "integer", "minimum": 0},
207
+ "full_trace": {
208
+ "type": "boolean",
209
+ "description": (
210
+ "Request a full internal trace response; disabled by default "
211
+ "unless the service is explicitly configured to allow it."
212
+ ),
213
+ },
214
+ },
215
+ },
216
+ "RunResponse": {
217
+ "type": "object",
218
+ "required": ["status"],
219
+ "properties": {
220
+ "status": {
221
+ "type": "string",
222
+ "enum": ["done", "failed"],
223
+ },
224
+ "answer": {"type": "string"},
225
+ "error": {"type": "string"},
226
+ "summary": {"type": "string"},
227
+ "trace_path": {"type": "string"},
228
+ "steps": {"type": "array", "items": {"type": "object"}},
229
+ },
230
+ "additionalProperties": True,
231
+ },
232
+ "RuntimeRunRequest": {
233
+ "type": "object",
234
+ "required": ["goal"],
235
+ "properties": {
236
+ "goal": {"type": "string", "maxLength": 4096},
237
+ "plan": {
238
+ "type": "object",
239
+ "description": (
240
+ "Optional strict runtime plan for deterministic tests; "
241
+ "when omitted the service uses configured LLM provider env."
242
+ ),
243
+ },
244
+ "plan_sequence": {
245
+ "type": "array",
246
+ "minItems": 1,
247
+ "items": {"type": "object"},
248
+ "description": (
249
+ "Optional ordered strict runtime plans for deterministic "
250
+ "replay tests; mutually exclusive with plan."
251
+ ),
252
+ },
253
+ "max_iterations": {
254
+ "type": "integer",
255
+ "minimum": 1,
256
+ "description": (
257
+ "Bounded by the service runtime_max_iterations configuration."
258
+ ),
259
+ },
260
+ "approved_action_ids": {
261
+ "type": "array",
262
+ "uniqueItems": True,
263
+ "items": {"type": "string", "minLength": 1},
264
+ "description": (
265
+ "Only valid with deterministic plan or plan_sequence "
266
+ "payloads; approve live provider actions through "
267
+ "/runtime/resume."
268
+ ),
269
+ },
270
+ "metadata": {
271
+ "type": "object",
272
+ "maxProperties": 16,
273
+ "additionalProperties": {
274
+ "type": "string",
275
+ "maxLength": 256,
276
+ },
277
+ "description": (
278
+ "Optional non-secret string metadata for internal "
279
+ "audit and filtering."
280
+ ),
281
+ },
282
+ "tags": {
283
+ "type": "array",
284
+ "maxItems": 16,
285
+ "uniqueItems": True,
286
+ "items": {
287
+ "type": "string",
288
+ "minLength": 1,
289
+ "maxLength": 64,
290
+ },
291
+ "description": (
292
+ "Optional non-secret run tags for internal audit "
293
+ "and filtering."
294
+ ),
295
+ },
296
+ },
297
+ "additionalProperties": False,
298
+ },
299
+ "RuntimeResumeRequest": {
300
+ "type": "object",
301
+ "required": ["run_id", "approved_action_ids"],
302
+ "properties": {
303
+ "run_id": {"type": "string"},
304
+ "approved_action_ids": {
305
+ "type": "array",
306
+ "uniqueItems": True,
307
+ "items": {"type": "string", "minLength": 1},
308
+ },
309
+ "max_iterations": {"type": "integer", "minimum": 1},
310
+ },
311
+ "additionalProperties": False,
312
+ },
313
+ "RuntimeCancelRequest": {
314
+ "type": "object",
315
+ "properties": {
316
+ "reason": {
317
+ "type": "string",
318
+ "maxLength": 500,
319
+ "description": (
320
+ "Optional operator-visible cancellation reason."
321
+ ),
322
+ }
323
+ },
324
+ "additionalProperties": False,
325
+ },
326
+ "RuntimeRunResponse": {
327
+ "type": "object",
328
+ "required": ["trace_type", "status", "plan", "observations", "events"],
329
+ "properties": {
330
+ "trace_type": {
331
+ "type": "string",
332
+ "const": RUNTIME_TRACE_TYPE,
333
+ },
334
+ "runtime_engine": {
335
+ "type": "string",
336
+ "enum": ["langgraph"],
337
+ },
338
+ "status": {
339
+ "type": "string",
340
+ "enum": [
341
+ "cancelled",
342
+ "done",
343
+ "failed",
344
+ "requires_approval",
345
+ ],
346
+ },
347
+ "run_id": {"type": "string"},
348
+ "goal": {"type": "string"},
349
+ "auth_subject": {"type": "string"},
350
+ "resumed_by_auth_subject": {"type": "string"},
351
+ "approved_by_auth_subject": {"type": "string"},
352
+ "approved_at": {"type": "string"},
353
+ "answer": {"type": "string"},
354
+ "final_answer_guardrail": _final_answer_guardrail_schema(),
355
+ "trace_path": {"type": "string"},
356
+ "duration_seconds": {
357
+ "type": "string",
358
+ "pattern": r"^\d+\.\d{4}$",
359
+ },
360
+ "iteration_count": {"type": "string"},
361
+ "max_iterations": {"type": "string"},
362
+ "iteration_budget_remaining": {"type": "string"},
363
+ "prompt_observation_compaction": {"type": "object"},
364
+ "llm_provider_request": _llm_provider_request_schema(),
365
+ "approved_action_count": {"type": "string"},
366
+ "approved_action_ids": {
367
+ "type": "array",
368
+ "items": {"type": "string"},
369
+ },
370
+ "metadata": {
371
+ "type": "object",
372
+ "additionalProperties": {"type": "string"},
373
+ },
374
+ "tags": {
375
+ "type": "array",
376
+ "items": {"type": "string"},
377
+ },
378
+ "plan": {"type": "object"},
379
+ "plans": {"type": "array", "items": {"type": "object"}},
380
+ "steps": {
381
+ "type": "array",
382
+ "items": {"$ref": "#/components/schemas/RuntimeStep"},
383
+ },
384
+ "observations": {
385
+ "type": "array",
386
+ "items": {"$ref": "#/components/schemas/RuntimeObservation"},
387
+ },
388
+ "events": {
389
+ "type": "array",
390
+ "items": {"$ref": "#/components/schemas/RuntimeEvent"},
391
+ },
392
+ "progress_events": {
393
+ "type": "array",
394
+ "items": {"type": "object"},
395
+ },
396
+ "graph_phases": {
397
+ "type": "array",
398
+ "items": {"$ref": "#/components/schemas/RuntimeGraphPhase"},
399
+ },
400
+ "progress_event_sink_failure_count": {"type": "string"},
401
+ "hook_failure_count": {"type": "string"},
402
+ "error_code": {"type": "string"},
403
+ "error": {"type": "string"},
404
+ },
405
+ "additionalProperties": True,
406
+ },
407
+ "RuntimeStep": {
408
+ "type": "object",
409
+ "required": ["index", "state", "title"],
410
+ "properties": {
411
+ "index": {"type": "string"},
412
+ "state": {
413
+ "type": "string",
414
+ "enum": [
415
+ "done",
416
+ "failed",
417
+ "pending",
418
+ "waiting_approval",
419
+ ],
420
+ },
421
+ "title": {"type": "string"},
422
+ "detail": {"type": "string"},
423
+ },
424
+ "additionalProperties": False,
425
+ },
426
+ "RuntimeObservation": {
427
+ "type": "object",
428
+ "required": ["action_id", "tool", "status", "output"],
429
+ "properties": {
430
+ "action_id": {"type": "string"},
431
+ "tool": {"type": "string"},
432
+ "status": {
433
+ "type": "string",
434
+ "enum": ["ok", "failed", "requires_approval"],
435
+ },
436
+ "output": {"type": "object"},
437
+ "error_code": {"type": "string"},
438
+ "error": {"type": "string"},
439
+ "started_at": {"type": "string"},
440
+ "completed_at": {"type": "string"},
441
+ "duration_seconds": {
442
+ "type": "string",
443
+ "pattern": r"^\d+\.\d{4}$",
444
+ },
445
+ },
446
+ "additionalProperties": True,
447
+ },
448
+ "RuntimeEvent": {
449
+ "type": "object",
450
+ "required": ["node", "status"],
451
+ "properties": {
452
+ "node": {"type": "string"},
453
+ "status": {"type": "string"},
454
+ "iteration": {"type": "string"},
455
+ "action_id": {"type": "string"},
456
+ "tool": {"type": "string"},
457
+ "reason": {"type": "string"},
458
+ "action_count": {"type": "string"},
459
+ "started_at": {"type": "string"},
460
+ "completed_at": {"type": "string"},
461
+ "duration_seconds": {
462
+ "type": "string",
463
+ "pattern": r"^\d+\.\d{4}$",
464
+ },
465
+ },
466
+ "additionalProperties": True,
467
+ },
468
+ "RuntimeArtifactResponse": {
469
+ "type": "object",
470
+ "required": [
471
+ "trace_type",
472
+ "run_id",
473
+ "trace_path",
474
+ "action_id",
475
+ "tool",
476
+ "artifact",
477
+ ],
478
+ "properties": {
479
+ "trace_type": {
480
+ "type": "string",
481
+ "const": RUNTIME_TRACE_TYPE,
482
+ },
483
+ "run_id": {"type": "string"},
484
+ "trace_path": {"type": "string"},
485
+ "action_id": {"type": "string"},
486
+ "tool": {"type": "string"},
487
+ "artifact": _runtime_artifact_detail_schema(),
488
+ },
489
+ "additionalProperties": False,
490
+ },
491
+ "RuntimeArtifactListResponse": {
492
+ "type": "object",
493
+ "required": [
494
+ "trace_type",
495
+ "run_id",
496
+ "trace_path",
497
+ "count",
498
+ "artifacts",
499
+ ],
500
+ "properties": {
501
+ "trace_type": {
502
+ "type": "string",
503
+ "const": RUNTIME_TRACE_TYPE,
504
+ },
505
+ "run_id": {"type": "string"},
506
+ "trace_path": {"type": "string"},
507
+ "count": {"type": "string"},
508
+ "artifacts": {
509
+ "type": "array",
510
+ "items": _runtime_artifact_list_item_schema(),
511
+ },
512
+ },
513
+ "additionalProperties": False,
514
+ },
515
+ "RuntimeTimelineResponse": {
516
+ "type": "object",
517
+ "required": [
518
+ "trace_type",
519
+ "run_id",
520
+ "trace_path",
521
+ "event_count",
522
+ "step_count",
523
+ "progress_event_count",
524
+ "graph_phase_count",
525
+ "observation_count",
526
+ "steps",
527
+ "events",
528
+ "progress_events",
529
+ "graph_phases",
530
+ "observations",
531
+ ],
532
+ "properties": {
533
+ "trace_type": {
534
+ "type": "string",
535
+ "const": RUNTIME_TRACE_TYPE,
536
+ },
537
+ "run_id": {"type": "string"},
538
+ "trace_path": {"type": "string"},
539
+ "event_count": {"type": "string"},
540
+ "step_count": {"type": "string"},
541
+ "progress_event_count": {"type": "string"},
542
+ "graph_phase_count": {"type": "string"},
543
+ "observation_count": {"type": "string"},
544
+ "steps": {
545
+ "type": "array",
546
+ "items": {"$ref": "#/components/schemas/RuntimeStep"},
547
+ },
548
+ "events": {
549
+ "type": "array",
550
+ "items": {"type": "object"},
551
+ },
552
+ "progress_events": {
553
+ "type": "array",
554
+ "items": {"type": "object"},
555
+ },
556
+ "graph_phases": {
557
+ "type": "array",
558
+ "items": {"$ref": "#/components/schemas/RuntimeGraphPhase"},
559
+ },
560
+ "observations": {
561
+ "type": "array",
562
+ "items": {"type": "object"},
563
+ },
564
+ },
565
+ "additionalProperties": False,
566
+ },
567
+ "RuntimeRunStatusResponse": {
568
+ "type": "object",
569
+ "required": [
570
+ "trace_type",
571
+ "run_id",
572
+ "status",
573
+ "trace_path",
574
+ "plan_count",
575
+ "observation_count",
576
+ "event_count",
577
+ "progress_event_count",
578
+ ],
579
+ "properties": _runtime_run_status_properties(
580
+ include_pending_approval=True
581
+ ),
582
+ "additionalProperties": False,
583
+ },
584
+ "RuntimeRunListItemResponse": {
585
+ "type": "object",
586
+ "required": [
587
+ "trace_type",
588
+ "run_id",
589
+ "status",
590
+ "trace_path",
591
+ "plan_count",
592
+ "observation_count",
593
+ "event_count",
594
+ "progress_event_count",
595
+ ],
596
+ "properties": _runtime_run_status_properties(
597
+ include_pending_approval=False,
598
+ include_steps=False,
599
+ ),
600
+ "additionalProperties": False,
601
+ },
602
+ "RuntimeRunListResponse": {
603
+ "type": "object",
604
+ "required": ["runs", "count", "next_cursor", "has_more"],
605
+ "properties": {
606
+ "runs": {
607
+ "type": "array",
608
+ "items": {
609
+ "$ref": "#/components/schemas/RuntimeRunListItemResponse"
610
+ },
611
+ },
612
+ "count": {"type": "string"},
613
+ "next_cursor": {"type": "string"},
614
+ "has_more": {
615
+ "type": "string",
616
+ "enum": ["true", "false"],
617
+ },
618
+ },
619
+ "additionalProperties": False,
620
+ },
621
+ "RuntimeRunSummaryResponse": {
622
+ "type": "object",
623
+ "required": [
624
+ "trace_type",
625
+ "run_count",
626
+ "status_counts",
627
+ "lifecycle_state_counts",
628
+ "runtime_engine_counts",
629
+ "auth_subject_counts",
630
+ "approved_by_auth_subject_counts",
631
+ "tool_counts",
632
+ "error_code_counts",
633
+ "failed_observation_count",
634
+ "graph_phase_count",
635
+ "graph_phase_node_counts",
636
+ "progress_event_sink_failure_count",
637
+ "hook_failure_count",
638
+ "llm_provider_request_count",
639
+ "llm_provider_request_attempt_count",
640
+ "llm_provider_request_retry_count",
641
+ "llm_provider_request_status_counts",
642
+ "llm_provider_request_error_type_counts",
643
+ "llm_provider_request_http_status_counts",
644
+ "llm_provider_request_retryable_reason_counts",
645
+ "approval_required_count",
646
+ "approved_tool_counts",
647
+ "pending_approval_count",
648
+ "final_answer_guardrail_applied_count",
649
+ "final_answer_guardrail_reason_counts",
650
+ "artifact_count",
651
+ "artifact_total_bytes",
652
+ "tag_counts",
653
+ "metadata_key_counts",
654
+ ],
655
+ "properties": {
656
+ "trace_type": {
657
+ "type": "string",
658
+ "const": RUNTIME_TRACE_TYPE,
659
+ },
660
+ "run_count": {"type": "string"},
661
+ "status_counts": {
662
+ "type": "object",
663
+ "additionalProperties": {"type": "string"},
664
+ },
665
+ "lifecycle_state_counts": {
666
+ "type": "object",
667
+ "additionalProperties": {"type": "string"},
668
+ },
669
+ "runtime_engine_counts": {
670
+ "type": "object",
671
+ "additionalProperties": {"type": "string"},
672
+ },
673
+ "auth_subject_counts": {
674
+ "type": "object",
675
+ "additionalProperties": {"type": "string"},
676
+ },
677
+ "approved_by_auth_subject_counts": {
678
+ "type": "object",
679
+ "additionalProperties": {"type": "string"},
680
+ },
681
+ "tool_counts": {
682
+ "type": "object",
683
+ "additionalProperties": {"type": "string"},
684
+ },
685
+ "error_code_counts": {
686
+ "type": "object",
687
+ "additionalProperties": {"type": "string"},
688
+ },
689
+ "failed_observation_count": {"type": "string"},
690
+ "graph_phase_count": {"type": "string"},
691
+ "graph_phase_node_counts": {
692
+ "type": "object",
693
+ "additionalProperties": {"type": "string"},
694
+ },
695
+ "progress_event_sink_failure_count": {"type": "string"},
696
+ "hook_failure_count": {"type": "string"},
697
+ "llm_provider_request_count": {"type": "string"},
698
+ "llm_provider_request_attempt_count": {"type": "string"},
699
+ "llm_provider_request_retry_count": {"type": "string"},
700
+ "llm_provider_request_status_counts": {
701
+ "type": "object",
702
+ "additionalProperties": {"type": "string"},
703
+ },
704
+ "llm_provider_request_error_type_counts": {
705
+ "type": "object",
706
+ "additionalProperties": {"type": "string"},
707
+ },
708
+ "llm_provider_request_http_status_counts": {
709
+ "type": "object",
710
+ "additionalProperties": {"type": "string"},
711
+ },
712
+ "llm_provider_request_retryable_reason_counts": {
713
+ "type": "object",
714
+ "additionalProperties": {"type": "string"},
715
+ },
716
+ "approval_required_count": {"type": "string"},
717
+ "approved_tool_counts": {
718
+ "type": "object",
719
+ "additionalProperties": {"type": "string"},
720
+ },
721
+ "pending_approval_count": {"type": "string"},
722
+ "final_answer_guardrail_applied_count": {"type": "string"},
723
+ "final_answer_guardrail_reason_counts": {
724
+ "type": "object",
725
+ "additionalProperties": {"type": "string"},
726
+ },
727
+ "artifact_count": {"type": "string"},
728
+ "artifact_total_bytes": {"type": "string"},
729
+ "tag_counts": {
730
+ "type": "object",
731
+ "additionalProperties": {"type": "string"},
732
+ },
733
+ "metadata_key_counts": {
734
+ "type": "object",
735
+ "additionalProperties": {"type": "string"},
736
+ },
737
+ },
738
+ "additionalProperties": False,
739
+ },
740
+ "RuntimeApprovalQueueResponse": {
741
+ "type": "object",
742
+ "required": ["trace_type", "count", "approvals"],
743
+ "properties": {
744
+ "trace_type": {
745
+ "type": "string",
746
+ "const": RUNTIME_TRACE_TYPE,
747
+ },
748
+ "count": {"type": "string"},
749
+ "approvals": {
750
+ "type": "array",
751
+ "items": _runtime_approval_queue_item_schema(),
752
+ },
753
+ },
754
+ "additionalProperties": False,
755
+ },
756
+ "RuntimeApprovalSummaryResponse": {
757
+ "type": "object",
758
+ "required": [
759
+ "trace_type",
760
+ "pending_approval_count",
761
+ "stale_pending_count",
762
+ "max_pending_age_seconds",
763
+ "auth_subject_counts",
764
+ "tool_counts",
765
+ ],
766
+ "properties": {
767
+ "trace_type": {
768
+ "type": "string",
769
+ "const": RUNTIME_TRACE_TYPE,
770
+ },
771
+ "pending_approval_count": {"type": "string"},
772
+ "stale_pending_count": {"type": "string"},
773
+ "max_pending_age_seconds": {"type": "string"},
774
+ "auth_subject_counts": {
775
+ "type": "object",
776
+ "additionalProperties": {"type": "string"},
777
+ },
778
+ "tool_counts": {
779
+ "type": "object",
780
+ "additionalProperties": {"type": "string"},
781
+ },
782
+ },
783
+ "additionalProperties": False,
784
+ },
785
+ "RuntimePolicyResponse": {
786
+ "type": "object",
787
+ "required": [
788
+ "trace_type",
789
+ "auth_subject",
790
+ "is_admin",
791
+ "default_allowed_tools",
792
+ "global_allowed_tools",
793
+ "subject_policy_count",
794
+ "subject_allowed_tools",
795
+ "effective_allowed_tools",
796
+ "effective_policy_source",
797
+ "effective_tool_policy",
798
+ "effective_tool_policy_sha256",
799
+ ],
800
+ "properties": {
801
+ "trace_type": {
802
+ "type": "string",
803
+ "const": RUNTIME_TRACE_TYPE,
804
+ },
805
+ "auth_subject": {"type": "string"},
806
+ "is_admin": {"type": "string", "enum": ["true", "false"]},
807
+ "default_allowed_tools": {
808
+ "type": "array",
809
+ "items": {"type": "string"},
810
+ },
811
+ "global_allowed_tools": {
812
+ "type": "array",
813
+ "items": {"type": "string"},
814
+ },
815
+ "subject_policy_count": {"type": "string"},
816
+ "subject_allowed_tools": {
817
+ "type": "object",
818
+ "additionalProperties": {
819
+ "type": "array",
820
+ "items": {"type": "string"},
821
+ },
822
+ },
823
+ "effective_allowed_tools": {
824
+ "type": "array",
825
+ "items": {"type": "string"},
826
+ },
827
+ "effective_policy_source": {
828
+ "type": "string",
829
+ "enum": ["default", "global", "subject"],
830
+ },
831
+ "effective_tool_policy": {
832
+ "type": "array",
833
+ "items": {
834
+ "type": "object",
835
+ "required": [
836
+ "name",
837
+ "allowed",
838
+ "approval_required",
839
+ ],
840
+ "properties": {
841
+ "name": {"type": "string"},
842
+ "allowed": {
843
+ "type": "string",
844
+ "enum": ["true", "false"],
845
+ },
846
+ "approval_required": {
847
+ "type": "string",
848
+ "enum": ["true", "false"],
849
+ },
850
+ },
851
+ "additionalProperties": False,
852
+ },
853
+ },
854
+ "effective_tool_policy_sha256": {
855
+ "type": "string",
856
+ "pattern": r"^[a-f0-9]{64}$",
857
+ },
858
+ },
859
+ "additionalProperties": False,
860
+ },
861
+ "ErrorResponse": {
862
+ "type": "object",
863
+ "required": ["status", "error_code", "error"],
864
+ "properties": {
865
+ "status": {"type": "string", "const": "failed"},
866
+ "error_code": {"type": "string", "enum": list(ERROR_CODES)},
867
+ "error": {"type": "string"},
868
+ "retry_after_seconds": {
869
+ "type": "string",
870
+ "pattern": r"^[1-9]\d*$",
871
+ },
872
+ },
873
+ }
874
+ },
875
+ },
876
+ "paths": {
877
+ "/health": {
878
+ "get": {
879
+ "summary": "Report service liveness",
880
+ "operationId": "getHealth",
881
+ "responses": {"200": _json_response("Service is live", "HealthResponse")},
882
+ },
883
+ "head": {
884
+ "summary": "Report service liveness headers",
885
+ "operationId": "headHealth",
886
+ "responses": {"200": _empty_response("Service is live")},
887
+ },
888
+ },
889
+ "/ready": {
890
+ "get": {
891
+ "summary": "Report service readiness",
892
+ "operationId": "getReady",
893
+ "responses": {
894
+ "200": _json_response("Service is ready", "ReadinessResponse"),
895
+ "503": _json_response("Service is not ready", "ReadinessResponse"),
896
+ },
897
+ },
898
+ "head": {
899
+ "summary": "Report service readiness headers",
900
+ "operationId": "headReady",
901
+ "responses": {
902
+ "200": _empty_response("Service is ready"),
903
+ "503": _empty_response("Service is not ready"),
904
+ },
905
+ },
906
+ },
907
+ "/config": {
908
+ "get": {
909
+ "summary": "Report redacted runtime configuration",
910
+ "description": _diagnostic_description(),
911
+ "security": _diagnostic_security(),
912
+ "operationId": "getConfig",
913
+ "responses": {
914
+ "200": _json_response("Redacted runtime config", "ConfigResponse")
915
+ },
916
+ }
917
+ },
918
+ "/version": {
919
+ "get": {
920
+ "summary": "Report package version",
921
+ "operationId": "getVersion",
922
+ "responses": {"200": _json_response("Package version", "VersionResponse")},
923
+ }
924
+ },
925
+ "/tools": {
926
+ "get": {
927
+ "summary": "List deterministic tool metadata",
928
+ "description": _diagnostic_description(),
929
+ "security": _diagnostic_security(),
930
+ "operationId": "getTools",
931
+ "responses": {"200": _json_response("Tool metadata", "ToolsResponse")},
932
+ }
933
+ },
934
+ "/runtime/graph": {
935
+ "get": {
936
+ "summary": "Report Codex-style runtime graph topology",
937
+ "description": _diagnostic_description(),
938
+ "security": _diagnostic_security(),
939
+ "operationId": "getRuntimeGraph",
940
+ "responses": {
941
+ "200": _json_response(
942
+ "Runtime graph topology",
943
+ "RuntimeGraphResponse",
944
+ )
945
+ },
946
+ }
947
+ },
948
+ "/runtime/tools": {
949
+ "get": {
950
+ "summary": "List Codex-style runtime tool metadata",
951
+ "description": _diagnostic_description(),
952
+ "security": _diagnostic_security(),
953
+ "operationId": "getRuntimeTools",
954
+ "responses": {
955
+ "200": _json_response(
956
+ "Runtime tool metadata",
957
+ "RuntimeToolsResponse",
958
+ )
959
+ },
960
+ }
961
+ },
962
+ "/runtime/policy": {
963
+ "get": {
964
+ "summary": "Report Codex-style runtime tool policy",
965
+ "description": _diagnostic_description(),
966
+ "security": _diagnostic_security(),
967
+ "operationId": "getRuntimePolicy",
968
+ "responses": {
969
+ "200": _json_response(
970
+ "Runtime tool execution policy",
971
+ "RuntimePolicyResponse",
972
+ ),
973
+ "401": _error_response("Missing or invalid bearer token"),
974
+ },
975
+ }
976
+ },
977
+ "/metrics": {
978
+ "get": {
979
+ "summary": "Report runtime request counters",
980
+ "description": _diagnostic_description(),
981
+ "security": _diagnostic_security(),
982
+ "operationId": "getMetrics",
983
+ "responses": {"200": _json_response("Runtime metrics", "MetricsResponse")},
984
+ }
985
+ },
986
+ "/metrics.prom": {
987
+ "get": {
988
+ "summary": "Report Prometheus text metrics",
989
+ "description": _diagnostic_description(),
990
+ "security": _diagnostic_security(),
991
+ "operationId": "getPrometheusMetrics",
992
+ "responses": {"200": _text_response("Prometheus text metrics")},
993
+ }
994
+ },
995
+ "/openapi.json": {
996
+ "get": {
997
+ "summary": "Report this API contract",
998
+ "description": _diagnostic_description(),
999
+ "security": _diagnostic_security(),
1000
+ "operationId": "getOpenApi",
1001
+ "responses": {"200": _object_response("OpenAPI contract")},
1002
+ }
1003
+ },
1004
+ "/run": {
1005
+ "options": {
1006
+ "summary": "Report supported HTTP methods",
1007
+ "operationId": "optionsRun",
1008
+ "responses": {
1009
+ "204": {
1010
+ "description": f"Allow: {ALLOWED_HTTP_METHODS}",
1011
+ "headers": _response_headers(
1012
+ {
1013
+ "Allow": {
1014
+ "description": "Supported HTTP methods",
1015
+ "schema": {
1016
+ "type": "string",
1017
+ "const": ALLOWED_HTTP_METHODS,
1018
+ },
1019
+ }
1020
+ }
1021
+ ),
1022
+ }
1023
+ },
1024
+ },
1025
+ "post": {
1026
+ "summary": "Run one bounded agent goal",
1027
+ "operationId": "postRun",
1028
+ "security": [{"BearerAuth": []}],
1029
+ "parameters": [_idempotency_key_parameter()],
1030
+ "requestBody": {
1031
+ "required": True,
1032
+ "content": {
1033
+ "application/json": {
1034
+ "schema": {"$ref": "#/components/schemas/RunRequest"}
1035
+ }
1036
+ },
1037
+ },
1038
+ "responses": {
1039
+ "200": _json_response(
1040
+ "Agent run completed or failed structurally",
1041
+ "RunResponse",
1042
+ headers={
1043
+ "X-Run-ID": {
1044
+ "description": (
1045
+ "Agent run identifier for request/log/trace correlation"
1046
+ ),
1047
+ "schema": {"type": "string"},
1048
+ },
1049
+ "X-Trace-Path": {
1050
+ "description": (
1051
+ "Persisted trace artifact path when trace persistence "
1052
+ "is enabled"
1053
+ ),
1054
+ "schema": {"type": "string"},
1055
+ }
1056
+ },
1057
+ ),
1058
+ "400": _error_response(
1059
+ "Malformed JSON, incomplete body, unsupported transfer encoding, "
1060
+ "missing goal, or invalid config"
1061
+ ),
1062
+ "401": _error_response(
1063
+ "Missing or invalid bearer token",
1064
+ headers={
1065
+ "WWW-Authenticate": {
1066
+ "description": "Bearer authentication challenge",
1067
+ "schema": {"type": "string", "const": "Bearer"},
1068
+ }
1069
+ },
1070
+ ),
1071
+ "403": _error_response("Full trace responses are disabled"),
1072
+ "408": _error_response(
1073
+ "Request body read timed out",
1074
+ headers={
1075
+ "Retry-After": {
1076
+ "description": "Suggested retry delay in seconds",
1077
+ "schema": {"type": "string", "const": "1"},
1078
+ }
1079
+ },
1080
+ ),
1081
+ "409": _error_response(
1082
+ "Idempotency key conflicts with another request body or the "
1083
+ "matching request is still in progress"
1084
+ ),
1085
+ "413": _error_response("Request body is too large"),
1086
+ "415": _error_response(
1087
+ "Content-Type is missing, duplicated, or not "
1088
+ "single-valued application/json"
1089
+ ),
1090
+ "417": _error_response("Expect request headers are unsupported"),
1091
+ "429": _error_response(
1092
+ "Rate limit exceeded",
1093
+ headers={
1094
+ "Retry-After": {
1095
+ "description": "Suggested retry delay in seconds",
1096
+ "schema": {"type": "string", "pattern": r"^[1-9]\d*$"},
1097
+ }
1098
+ },
1099
+ ),
1100
+ "500": _error_response("Agent run or trace persistence failed"),
1101
+ "503": _error_response(
1102
+ "Too many concurrent agent runs",
1103
+ headers={
1104
+ "Retry-After": {
1105
+ "description": "Suggested retry delay in seconds",
1106
+ "schema": {"type": "string", "const": "1"},
1107
+ }
1108
+ },
1109
+ ),
1110
+ "504": _error_response("Agent run timed out"),
1111
+ },
1112
+ }
1113
+ },
1114
+ "/runtime/run": {
1115
+ "post": {
1116
+ "summary": "Run one Codex-style runtime goal",
1117
+ "description": (
1118
+ "Execute the LLM-planned runtime path. A request may include "
1119
+ "a strict plan object for deterministic tests; otherwise the "
1120
+ "runtime uses configured OpenAI-compatible provider settings."
1121
+ ),
1122
+ "operationId": "postRuntimeRun",
1123
+ "security": [{"BearerAuth": []}],
1124
+ "parameters": [_idempotency_key_parameter()],
1125
+ "requestBody": {
1126
+ "required": True,
1127
+ "content": {
1128
+ "application/json": {
1129
+ "schema": {
1130
+ "$ref": "#/components/schemas/RuntimeRunRequest"
1131
+ }
1132
+ }
1133
+ },
1134
+ },
1135
+ "responses": {
1136
+ "200": _json_response(
1137
+ "Runtime run completed, failed, or requires approval",
1138
+ "RuntimeRunResponse",
1139
+ headers={
1140
+ "X-Trace-Path": {
1141
+ "description": (
1142
+ "Persisted runtime trace artifact path when trace "
1143
+ "persistence is enabled"
1144
+ ),
1145
+ "schema": {"type": "string"},
1146
+ }
1147
+ },
1148
+ ),
1149
+ "400": _error_response("Malformed runtime request or provider config"),
1150
+ "401": _error_response("Missing or invalid bearer token"),
1151
+ "409": _error_response(
1152
+ "Idempotency key conflicts with another request body or the "
1153
+ "matching request is still in progress"
1154
+ ),
1155
+ "413": _error_response("Request body is too large"),
1156
+ "415": _error_response(
1157
+ "Content-Type is missing, duplicated, or not "
1158
+ "single-valued application/json"
1159
+ ),
1160
+ "429": _error_response(
1161
+ "Rate limit exceeded",
1162
+ headers={
1163
+ "Retry-After": {
1164
+ "description": "Suggested retry delay in seconds",
1165
+ "schema": {"type": "string", "pattern": r"^[1-9]\d*$"},
1166
+ }
1167
+ },
1168
+ ),
1169
+ "503": _error_response("Run concurrency limit is full"),
1170
+ "504": _error_response("Agent run timed out"),
1171
+ },
1172
+ }
1173
+ },
1174
+ "/runtime/resume": {
1175
+ "post": {
1176
+ "summary": "Resume one Codex-style runtime run after approval",
1177
+ "description": (
1178
+ "Load a persisted runtime trace by run_id and continue a "
1179
+ "policy-blocked action using explicit approved_action_ids."
1180
+ ),
1181
+ "operationId": "postRuntimeResume",
1182
+ "security": [{"BearerAuth": []}],
1183
+ "parameters": [_idempotency_key_parameter()],
1184
+ "requestBody": {
1185
+ "required": True,
1186
+ "content": {
1187
+ "application/json": {
1188
+ "schema": {
1189
+ "$ref": "#/components/schemas/RuntimeResumeRequest"
1190
+ }
1191
+ }
1192
+ },
1193
+ },
1194
+ "responses": {
1195
+ "200": _json_response(
1196
+ "Runtime run resumed after approval",
1197
+ "RuntimeRunResponse",
1198
+ headers={
1199
+ "X-Trace-Path": {
1200
+ "description": (
1201
+ "Persisted resumed runtime trace artifact path"
1202
+ ),
1203
+ "schema": {"type": "string"},
1204
+ }
1205
+ },
1206
+ ),
1207
+ "400": _error_response("Malformed resume request or missing trace_dir"),
1208
+ "401": _error_response("Missing or invalid bearer token"),
1209
+ "404": _error_response("Persisted runtime run was not found"),
1210
+ "409": _error_response(
1211
+ "Idempotency key conflicts with another request body or the "
1212
+ "matching request is still in progress"
1213
+ ),
1214
+ "413": _error_response("Request body is too large"),
1215
+ "415": _error_response(
1216
+ "Content-Type is missing, duplicated, or not "
1217
+ "single-valued application/json"
1218
+ ),
1219
+ "429": _error_response(
1220
+ "Rate limit exceeded",
1221
+ headers={
1222
+ "Retry-After": {
1223
+ "description": "Suggested retry delay in seconds",
1224
+ "schema": {"type": "string", "pattern": r"^[1-9]\d*$"},
1225
+ }
1226
+ },
1227
+ ),
1228
+ "500": _error_response("Trace read or persistence failed"),
1229
+ "503": _error_response("Run concurrency limit is full"),
1230
+ "504": _error_response("Agent run timed out"),
1231
+ },
1232
+ }
1233
+ },
1234
+ "/runtime/runs/{run_id}": {
1235
+ "get": {
1236
+ "summary": "Report one persisted Codex-style runtime run status",
1237
+ "description": _diagnostic_description(),
1238
+ "security": _diagnostic_security(),
1239
+ "operationId": "getRuntimeRunStatus",
1240
+ "parameters": [
1241
+ {
1242
+ "name": "run_id",
1243
+ "in": "path",
1244
+ "required": True,
1245
+ "description": "Persisted runtime run identifier",
1246
+ "schema": {"type": "string"},
1247
+ }
1248
+ ],
1249
+ "responses": {
1250
+ "200": _json_response(
1251
+ "Runtime run status",
1252
+ "RuntimeRunStatusResponse",
1253
+ ),
1254
+ "400": _error_response("Runtime trace persistence is not configured"),
1255
+ "401": _error_response("Missing or invalid bearer token"),
1256
+ "404": _error_response("Persisted runtime run was not found"),
1257
+ "500": _error_response("Runtime trace could not be read"),
1258
+ },
1259
+ }
1260
+ },
1261
+ "/runtime/runs/{run_id}/cancel": {
1262
+ "post": {
1263
+ "summary": "Cancel one pending Codex-style runtime run",
1264
+ "description": (
1265
+ "Load a persisted non-terminal runtime trace by run_id and "
1266
+ "mark it cancelled. The owning auth subject may cancel its "
1267
+ "own run; the primary token may cancel any subject run."
1268
+ ),
1269
+ "operationId": "postRuntimeCancel",
1270
+ "security": [{"BearerAuth": []}],
1271
+ "parameters": [
1272
+ {
1273
+ "name": "run_id",
1274
+ "in": "path",
1275
+ "required": True,
1276
+ "description": "Persisted runtime run identifier",
1277
+ "schema": {"type": "string"},
1278
+ },
1279
+ _idempotency_key_parameter(),
1280
+ ],
1281
+ "requestBody": {
1282
+ "required": True,
1283
+ "content": {
1284
+ "application/json": {
1285
+ "schema": {
1286
+ "$ref": "#/components/schemas/RuntimeCancelRequest"
1287
+ }
1288
+ }
1289
+ },
1290
+ },
1291
+ "responses": {
1292
+ "200": _json_response(
1293
+ "Runtime run was cancelled",
1294
+ "RuntimeRunStatusResponse",
1295
+ ),
1296
+ "400": _error_response("Malformed cancel request or missing trace_dir"),
1297
+ "401": _error_response("Missing or invalid bearer token"),
1298
+ "404": _error_response("Persisted runtime run was not found"),
1299
+ "409": _error_response("Runtime run is already terminal"),
1300
+ "413": _error_response("Request body is too large"),
1301
+ "415": _error_response(
1302
+ "Content-Type is missing, duplicated, or not "
1303
+ "single-valued application/json"
1304
+ ),
1305
+ "429": _error_response(
1306
+ "Rate limit exceeded",
1307
+ headers={
1308
+ "Retry-After": {
1309
+ "description": "Suggested retry delay in seconds",
1310
+ "schema": {"type": "string", "pattern": r"^[1-9]\d*$"},
1311
+ }
1312
+ },
1313
+ ),
1314
+ "500": _error_response("Trace read or persistence failed"),
1315
+ "503": _error_response("Run concurrency limit is full"),
1316
+ },
1317
+ }
1318
+ },
1319
+ "/runtime/runs/{run_id}/artifacts/{artifact_id}": {
1320
+ "get": {
1321
+ "summary": "Return one artifact from a persisted Codex-style runtime run",
1322
+ "description": _diagnostic_description(),
1323
+ "security": _diagnostic_security(),
1324
+ "operationId": "getRuntimeArtifact",
1325
+ "parameters": [
1326
+ {
1327
+ "name": "run_id",
1328
+ "in": "path",
1329
+ "required": True,
1330
+ "description": "Persisted runtime run identifier",
1331
+ "schema": {"type": "string"},
1332
+ },
1333
+ {
1334
+ "name": "artifact_id",
1335
+ "in": "path",
1336
+ "required": True,
1337
+ "description": "Artifact identifier from compact runtime status",
1338
+ "schema": {"type": "string"},
1339
+ },
1340
+ ],
1341
+ "responses": {
1342
+ "200": _json_response(
1343
+ "Runtime artifact",
1344
+ "RuntimeArtifactResponse",
1345
+ ),
1346
+ "400": _error_response("Runtime trace persistence is not configured"),
1347
+ "401": _error_response("Missing or invalid bearer token"),
1348
+ "404": _error_response(
1349
+ "Persisted runtime run or artifact was not found"
1350
+ ),
1351
+ "500": _error_response("Runtime trace could not be read"),
1352
+ },
1353
+ }
1354
+ },
1355
+ "/runtime/runs/{run_id}/artifacts": {
1356
+ "get": {
1357
+ "summary": (
1358
+ "List artifact metadata for one persisted Codex-style runtime run"
1359
+ ),
1360
+ "description": _diagnostic_description(),
1361
+ "security": _diagnostic_security(),
1362
+ "operationId": "listRuntimeArtifacts",
1363
+ "parameters": [
1364
+ {
1365
+ "name": "run_id",
1366
+ "in": "path",
1367
+ "required": True,
1368
+ "description": "Persisted runtime run identifier",
1369
+ "schema": {"type": "string"},
1370
+ }
1371
+ ],
1372
+ "responses": {
1373
+ "200": _json_response(
1374
+ "Runtime artifact metadata list",
1375
+ "RuntimeArtifactListResponse",
1376
+ ),
1377
+ "400": _error_response("Runtime trace persistence is not configured"),
1378
+ "401": _error_response("Missing or invalid bearer token"),
1379
+ "404": _error_response("Persisted runtime run was not found"),
1380
+ "500": _error_response("Runtime trace could not be read"),
1381
+ },
1382
+ }
1383
+ },
1384
+ "/runtime/runs/{run_id}/timeline": {
1385
+ "get": {
1386
+ "summary": "Return a compact timeline for one persisted runtime run",
1387
+ "description": _diagnostic_description(),
1388
+ "security": _diagnostic_security(),
1389
+ "operationId": "getRuntimeTimeline",
1390
+ "parameters": [
1391
+ {
1392
+ "name": "run_id",
1393
+ "in": "path",
1394
+ "required": True,
1395
+ "description": "Persisted runtime run identifier",
1396
+ "schema": {"type": "string"},
1397
+ }
1398
+ ],
1399
+ "responses": {
1400
+ "200": _json_response(
1401
+ "Runtime compact timeline",
1402
+ "RuntimeTimelineResponse",
1403
+ ),
1404
+ "400": _error_response("Runtime trace persistence is not configured"),
1405
+ "401": _error_response("Missing or invalid bearer token"),
1406
+ "404": _error_response("Persisted runtime run was not found"),
1407
+ "500": _error_response("Runtime trace could not be read"),
1408
+ },
1409
+ }
1410
+ },
1411
+ "/runtime/approvals": {
1412
+ "get": {
1413
+ "summary": "List pending Codex-style runtime approvals",
1414
+ "description": _diagnostic_description(),
1415
+ "security": _diagnostic_security(),
1416
+ "operationId": "listRuntimeApprovals",
1417
+ "parameters": [
1418
+ {
1419
+ "name": "limit",
1420
+ "in": "query",
1421
+ "required": False,
1422
+ "description": (
1423
+ "Maximum pending approval records to return, "
1424
+ "from 1 to 100"
1425
+ ),
1426
+ "schema": {
1427
+ "type": "integer",
1428
+ "minimum": 1,
1429
+ "maximum": 100,
1430
+ "default": 50,
1431
+ },
1432
+ },
1433
+ {
1434
+ "name": "auth_subject",
1435
+ "in": "query",
1436
+ "required": False,
1437
+ "description": (
1438
+ "Filter pending approvals by authenticated "
1439
+ "internal subject"
1440
+ ),
1441
+ "schema": {"type": "string", "minLength": 1},
1442
+ },
1443
+ {
1444
+ "name": "tool",
1445
+ "in": "query",
1446
+ "required": False,
1447
+ "description": "Filter pending approvals by tool name",
1448
+ "schema": {"type": "string", "minLength": 1},
1449
+ },
1450
+ {
1451
+ "name": "min_pending_age_seconds",
1452
+ "in": "query",
1453
+ "required": False,
1454
+ "description": (
1455
+ "Filter pending approvals older than this many seconds"
1456
+ ),
1457
+ "schema": {"type": "integer", "minimum": 0},
1458
+ },
1459
+ ],
1460
+ "responses": {
1461
+ "200": _json_response(
1462
+ "Runtime pending approval queue",
1463
+ "RuntimeApprovalQueueResponse",
1464
+ ),
1465
+ "400": _error_response("Runtime trace persistence is not configured"),
1466
+ "401": _error_response("Missing or invalid bearer token"),
1467
+ },
1468
+ }
1469
+ },
1470
+ "/runtime/approvals/summary": {
1471
+ "get": {
1472
+ "summary": "Summarize pending Codex-style runtime approvals",
1473
+ "description": _diagnostic_description(),
1474
+ "security": _diagnostic_security(),
1475
+ "operationId": "summarizeRuntimeApprovals",
1476
+ "parameters": [
1477
+ {
1478
+ "name": "auth_subject",
1479
+ "in": "query",
1480
+ "required": False,
1481
+ "description": (
1482
+ "Filter pending approval aggregate by "
1483
+ "authenticated internal subject"
1484
+ ),
1485
+ "schema": {"type": "string", "minLength": 1},
1486
+ },
1487
+ {
1488
+ "name": "tool",
1489
+ "in": "query",
1490
+ "required": False,
1491
+ "description": "Filter pending approval aggregate by tool name",
1492
+ "schema": {"type": "string", "minLength": 1},
1493
+ },
1494
+ {
1495
+ "name": "min_pending_age_seconds",
1496
+ "in": "query",
1497
+ "required": False,
1498
+ "description": (
1499
+ "Filter pending approvals older than this many seconds"
1500
+ ),
1501
+ "schema": {"type": "integer", "minimum": 0},
1502
+ },
1503
+ ],
1504
+ "responses": {
1505
+ "200": _json_response(
1506
+ "Runtime pending approval aggregate",
1507
+ "RuntimeApprovalSummaryResponse",
1508
+ ),
1509
+ "400": _error_response("Runtime trace persistence is not configured"),
1510
+ "401": _error_response("Missing or invalid bearer token"),
1511
+ },
1512
+ }
1513
+ },
1514
+ "/runtime/runs": {
1515
+ "get": {
1516
+ "summary": "List persisted Codex-style runtime run statuses",
1517
+ "description": _diagnostic_description(),
1518
+ "security": _diagnostic_security(),
1519
+ "operationId": "listRuntimeRuns",
1520
+ "parameters": [
1521
+ {
1522
+ "name": "limit",
1523
+ "in": "query",
1524
+ "required": False,
1525
+ "description": (
1526
+ "Maximum persisted runtime runs to return, from 1 to 100"
1527
+ ),
1528
+ "schema": {
1529
+ "type": "integer",
1530
+ "minimum": 1,
1531
+ "maximum": 100,
1532
+ "default": 50,
1533
+ },
1534
+ },
1535
+ {
1536
+ "name": "cursor",
1537
+ "in": "query",
1538
+ "required": False,
1539
+ "description": (
1540
+ "Opaque pagination cursor from a previous runtime "
1541
+ "run list response"
1542
+ ),
1543
+ "schema": {"type": "string", "minLength": 1},
1544
+ },
1545
+ {
1546
+ "name": "auth_subject",
1547
+ "in": "query",
1548
+ "required": False,
1549
+ "description": (
1550
+ "Filter persisted runtime runs by authenticated "
1551
+ "internal subject"
1552
+ ),
1553
+ "schema": {"type": "string", "minLength": 1},
1554
+ },
1555
+ {
1556
+ "name": "status",
1557
+ "in": "query",
1558
+ "required": False,
1559
+ "description": "Filter persisted runtime runs by status",
1560
+ "schema": {
1561
+ "type": "string",
1562
+ "enum": [
1563
+ "cancelled",
1564
+ "done",
1565
+ "failed",
1566
+ "requires_approval",
1567
+ "resumed",
1568
+ "resuming",
1569
+ "running",
1570
+ ],
1571
+ },
1572
+ },
1573
+ {
1574
+ "name": "lifecycle_state",
1575
+ "in": "query",
1576
+ "required": False,
1577
+ "description": (
1578
+ "Filter persisted runtime runs by derived operator "
1579
+ "lifecycle state"
1580
+ ),
1581
+ "schema": {
1582
+ "type": "string",
1583
+ "enum": [
1584
+ "cancelled",
1585
+ "failed",
1586
+ "planning",
1587
+ "running",
1588
+ "succeeded",
1589
+ "unknown",
1590
+ "waiting_approval",
1591
+ ],
1592
+ },
1593
+ },
1594
+ {
1595
+ "name": "tool",
1596
+ "in": "query",
1597
+ "required": False,
1598
+ "description": (
1599
+ "Filter persisted runtime runs whose compact "
1600
+ "tool_names include this tool"
1601
+ ),
1602
+ "schema": {"type": "string", "minLength": 1},
1603
+ },
1604
+ {
1605
+ "name": "error_code",
1606
+ "in": "query",
1607
+ "required": False,
1608
+ "description": (
1609
+ "Filter persisted runtime runs whose compact "
1610
+ "error_code_counts include this error code"
1611
+ ),
1612
+ "schema": {"type": "string", "minLength": 1},
1613
+ },
1614
+ {
1615
+ "name": "latest_failed_error_code",
1616
+ "in": "query",
1617
+ "required": False,
1618
+ "description": (
1619
+ "Filter persisted runtime runs whose compact "
1620
+ "latest_failed_error_code matches this error code"
1621
+ ),
1622
+ "schema": {"type": "string", "minLength": 1},
1623
+ },
1624
+ {
1625
+ "name": "latest_failed_action_id",
1626
+ "in": "query",
1627
+ "required": False,
1628
+ "description": (
1629
+ "Filter persisted runtime runs whose compact "
1630
+ "latest_failed_action_id matches this action id"
1631
+ ),
1632
+ "schema": {"type": "string", "minLength": 1},
1633
+ },
1634
+ {
1635
+ "name": "latest_failed_tool",
1636
+ "in": "query",
1637
+ "required": False,
1638
+ "description": (
1639
+ "Filter persisted runtime runs whose compact "
1640
+ "latest_failed_tool matches this tool"
1641
+ ),
1642
+ "schema": {"type": "string", "minLength": 1},
1643
+ },
1644
+ {
1645
+ "name": "llm_provider_status",
1646
+ "in": "query",
1647
+ "required": False,
1648
+ "description": (
1649
+ "Filter persisted runtime runs whose compact "
1650
+ "llm_provider_request_status matches this status"
1651
+ ),
1652
+ "schema": {"type": "string", "minLength": 1},
1653
+ },
1654
+ {
1655
+ "name": "llm_provider_error_type",
1656
+ "in": "query",
1657
+ "required": False,
1658
+ "description": (
1659
+ "Filter persisted runtime runs whose compact "
1660
+ "llm_provider_request_error_type matches this type"
1661
+ ),
1662
+ "schema": {"type": "string", "minLength": 1},
1663
+ },
1664
+ {
1665
+ "name": "llm_provider_http_status",
1666
+ "in": "query",
1667
+ "required": False,
1668
+ "description": (
1669
+ "Filter persisted runtime runs whose compact "
1670
+ "llm_provider_request_http_status matches this code"
1671
+ ),
1672
+ "schema": {"type": "string", "minLength": 1},
1673
+ },
1674
+ {
1675
+ "name": "llm_provider_retryable_reason",
1676
+ "in": "query",
1677
+ "required": False,
1678
+ "description": (
1679
+ "Filter persisted runtime runs whose compact "
1680
+ "llm_provider_request_retryable_reason matches this reason"
1681
+ ),
1682
+ "schema": {"type": "string", "minLength": 1},
1683
+ },
1684
+ {
1685
+ "name": "iteration_budget_remaining",
1686
+ "in": "query",
1687
+ "required": False,
1688
+ "description": (
1689
+ "Filter persisted runtime runs whose compact "
1690
+ "iteration_budget_remaining equals this count"
1691
+ ),
1692
+ "schema": {"type": "integer", "minimum": 0},
1693
+ },
1694
+ {
1695
+ "name": "artifact_kind",
1696
+ "in": "query",
1697
+ "required": False,
1698
+ "description": (
1699
+ "Filter persisted runtime runs whose compact "
1700
+ "artifact_kinds include this artifact kind"
1701
+ ),
1702
+ "schema": {"type": "string", "minLength": 1},
1703
+ },
1704
+ {
1705
+ "name": "artifact_format",
1706
+ "in": "query",
1707
+ "required": False,
1708
+ "description": (
1709
+ "Filter persisted runtime runs whose compact "
1710
+ "artifact_formats include this artifact format"
1711
+ ),
1712
+ "schema": {"type": "string", "minLength": 1},
1713
+ },
1714
+ {
1715
+ "name": "artifact_tag",
1716
+ "in": "query",
1717
+ "required": False,
1718
+ "description": (
1719
+ "Filter persisted runtime runs whose compact "
1720
+ "artifact_tags include this artifact tag"
1721
+ ),
1722
+ "schema": {"type": "string", "minLength": 1},
1723
+ },
1724
+ {
1725
+ "name": "tag",
1726
+ "in": "query",
1727
+ "required": False,
1728
+ "description": (
1729
+ "Filter persisted runtime runs whose compact tags "
1730
+ "include this tag"
1731
+ ),
1732
+ "schema": {"type": "string", "minLength": 1},
1733
+ },
1734
+ {
1735
+ "name": "metadata_key",
1736
+ "in": "query",
1737
+ "required": False,
1738
+ "description": (
1739
+ "Filter persisted runtime runs whose compact "
1740
+ "metadata contains this key"
1741
+ ),
1742
+ "schema": {"type": "string", "minLength": 1},
1743
+ },
1744
+ {
1745
+ "name": "metadata_value",
1746
+ "in": "query",
1747
+ "required": False,
1748
+ "description": (
1749
+ "Filter persisted runtime runs whose compact "
1750
+ "metadata contains this value"
1751
+ ),
1752
+ "schema": {"type": "string", "minLength": 1},
1753
+ },
1754
+ {
1755
+ "name": "has_artifacts",
1756
+ "in": "query",
1757
+ "required": False,
1758
+ "description": (
1759
+ "Filter persisted runtime runs by whether "
1760
+ "artifacts were produced"
1761
+ ),
1762
+ "schema": {"type": "boolean"},
1763
+ },
1764
+ {
1765
+ "name": "has_errors",
1766
+ "in": "query",
1767
+ "required": False,
1768
+ "description": (
1769
+ "Filter persisted runtime runs by whether compact "
1770
+ "summaries contain observation or run-level errors"
1771
+ ),
1772
+ "schema": {"type": "boolean"},
1773
+ },
1774
+ {
1775
+ "name": "has_failures",
1776
+ "in": "query",
1777
+ "required": False,
1778
+ "description": (
1779
+ "Filter persisted runtime runs by whether compact "
1780
+ "summaries contain failed observations"
1781
+ ),
1782
+ "schema": {"type": "boolean"},
1783
+ },
1784
+ {
1785
+ "name": "has_approvals",
1786
+ "in": "query",
1787
+ "required": False,
1788
+ "description": (
1789
+ "Filter persisted runtime runs by whether compact "
1790
+ "summaries contain approved actions"
1791
+ ),
1792
+ "schema": {"type": "boolean"},
1793
+ },
1794
+ {
1795
+ "name": "has_pending_approval",
1796
+ "in": "query",
1797
+ "required": False,
1798
+ "description": (
1799
+ "Filter persisted runtime runs by whether compact "
1800
+ "summaries contain a pending approval action"
1801
+ ),
1802
+ "schema": {"type": "boolean"},
1803
+ },
1804
+ {
1805
+ "name": "has_final_answer_guardrail",
1806
+ "in": "query",
1807
+ "required": False,
1808
+ "description": (
1809
+ "Filter persisted runtime runs by whether compact "
1810
+ "summaries contain an applied final-answer guardrail"
1811
+ ),
1812
+ "schema": {"type": "boolean"},
1813
+ },
1814
+ {
1815
+ "name": "has_llm_provider_retries",
1816
+ "in": "query",
1817
+ "required": False,
1818
+ "description": (
1819
+ "Filter persisted runtime runs by whether compact "
1820
+ "LLM provider diagnostics recorded retries"
1821
+ ),
1822
+ "schema": {"type": "boolean"},
1823
+ },
1824
+ {
1825
+ "name": "final_answer_guardrail_reason",
1826
+ "in": "query",
1827
+ "required": False,
1828
+ "description": (
1829
+ "Filter persisted runtime runs whose applied "
1830
+ "final-answer guardrail has this reason"
1831
+ ),
1832
+ "schema": {"type": "string", "minLength": 1},
1833
+ },
1834
+ {
1835
+ "name": "approved_action_id",
1836
+ "in": "query",
1837
+ "required": False,
1838
+ "description": (
1839
+ "Filter persisted runtime runs whose compact "
1840
+ "approved_action_ids include this action id"
1841
+ ),
1842
+ "schema": {"type": "string", "minLength": 1},
1843
+ },
1844
+ {
1845
+ "name": "approved_by_auth_subject",
1846
+ "in": "query",
1847
+ "required": False,
1848
+ "description": (
1849
+ "Filter persisted runtime runs by the subject "
1850
+ "that approved the pending action"
1851
+ ),
1852
+ "schema": {"type": "string", "minLength": 1},
1853
+ },
1854
+ {
1855
+ "name": "resumed_from_run_id",
1856
+ "in": "query",
1857
+ "required": False,
1858
+ "description": (
1859
+ "Filter persisted runtime runs resumed from this "
1860
+ "original run id"
1861
+ ),
1862
+ "schema": {"type": "string", "minLength": 1},
1863
+ },
1864
+ {
1865
+ "name": "resumed_by_auth_subject",
1866
+ "in": "query",
1867
+ "required": False,
1868
+ "description": (
1869
+ "Filter persisted runtime runs by the subject "
1870
+ "that performed resume"
1871
+ ),
1872
+ "schema": {"type": "string", "minLength": 1},
1873
+ },
1874
+ {
1875
+ "name": "pending_approval_tool",
1876
+ "in": "query",
1877
+ "required": False,
1878
+ "description": (
1879
+ "Filter persisted runtime runs whose compact "
1880
+ "pending_approval_tool matches this tool"
1881
+ ),
1882
+ "schema": {"type": "string", "minLength": 1},
1883
+ },
1884
+ {
1885
+ "name": "pending_approval_action_id",
1886
+ "in": "query",
1887
+ "required": False,
1888
+ "description": (
1889
+ "Filter persisted runtime runs whose compact "
1890
+ "pending_approval_action_id matches this action id"
1891
+ ),
1892
+ "schema": {"type": "string", "minLength": 1},
1893
+ },
1894
+ ],
1895
+ "responses": {
1896
+ "200": _json_response(
1897
+ "Runtime run status list",
1898
+ "RuntimeRunListResponse",
1899
+ ),
1900
+ "400": _error_response("Runtime trace persistence is not configured"),
1901
+ "401": _error_response("Missing or invalid bearer token"),
1902
+ },
1903
+ }
1904
+ },
1905
+ "/runtime/runs/summary": {
1906
+ "get": {
1907
+ "summary": "Summarize persisted Codex-style runtime runs",
1908
+ "description": _diagnostic_description(),
1909
+ "security": _diagnostic_security(),
1910
+ "operationId": "summarizeRuntimeRuns",
1911
+ "parameters": [
1912
+ {
1913
+ "name": "auth_subject",
1914
+ "in": "query",
1915
+ "required": False,
1916
+ "description": (
1917
+ "Filter summary to persisted runtime runs by "
1918
+ "authenticated internal subject"
1919
+ ),
1920
+ "schema": {"type": "string", "minLength": 1},
1921
+ },
1922
+ {
1923
+ "name": "status",
1924
+ "in": "query",
1925
+ "required": False,
1926
+ "description": "Filter summary by runtime status",
1927
+ "schema": {
1928
+ "type": "string",
1929
+ "enum": [
1930
+ "cancelled",
1931
+ "done",
1932
+ "failed",
1933
+ "requires_approval",
1934
+ "resumed",
1935
+ "resuming",
1936
+ "running",
1937
+ ],
1938
+ },
1939
+ },
1940
+ {
1941
+ "name": "tool",
1942
+ "in": "query",
1943
+ "required": False,
1944
+ "description": "Filter summary by compact tool_names",
1945
+ "schema": {"type": "string", "minLength": 1},
1946
+ },
1947
+ {
1948
+ "name": "error_code",
1949
+ "in": "query",
1950
+ "required": False,
1951
+ "description": "Filter summary by compact error_code_counts",
1952
+ "schema": {"type": "string", "minLength": 1},
1953
+ },
1954
+ {
1955
+ "name": "llm_provider_status",
1956
+ "in": "query",
1957
+ "required": False,
1958
+ "description": (
1959
+ "Filter summary by compact "
1960
+ "llm_provider_request_status"
1961
+ ),
1962
+ "schema": {"type": "string", "minLength": 1},
1963
+ },
1964
+ {
1965
+ "name": "llm_provider_error_type",
1966
+ "in": "query",
1967
+ "required": False,
1968
+ "description": (
1969
+ "Filter summary by compact "
1970
+ "llm_provider_request_error_type"
1971
+ ),
1972
+ "schema": {"type": "string", "minLength": 1},
1973
+ },
1974
+ {
1975
+ "name": "llm_provider_http_status",
1976
+ "in": "query",
1977
+ "required": False,
1978
+ "description": (
1979
+ "Filter summary by compact "
1980
+ "llm_provider_request_http_status"
1981
+ ),
1982
+ "schema": {"type": "string", "minLength": 1},
1983
+ },
1984
+ {
1985
+ "name": "llm_provider_retryable_reason",
1986
+ "in": "query",
1987
+ "required": False,
1988
+ "description": (
1989
+ "Filter summary by compact "
1990
+ "llm_provider_request_retryable_reason"
1991
+ ),
1992
+ "schema": {"type": "string", "minLength": 1},
1993
+ },
1994
+ {
1995
+ "name": "tag",
1996
+ "in": "query",
1997
+ "required": False,
1998
+ "description": "Filter summary by compact run tags",
1999
+ "schema": {"type": "string", "minLength": 1},
2000
+ },
2001
+ {
2002
+ "name": "metadata_key",
2003
+ "in": "query",
2004
+ "required": False,
2005
+ "description": "Filter summary by compact metadata key",
2006
+ "schema": {"type": "string", "minLength": 1},
2007
+ },
2008
+ {
2009
+ "name": "metadata_value",
2010
+ "in": "query",
2011
+ "required": False,
2012
+ "description": "Filter summary by compact metadata value",
2013
+ "schema": {"type": "string", "minLength": 1},
2014
+ },
2015
+ {
2016
+ "name": "has_pending_approval",
2017
+ "in": "query",
2018
+ "required": False,
2019
+ "description": (
2020
+ "Filter summary by whether compact summaries contain "
2021
+ "a pending approval action"
2022
+ ),
2023
+ "schema": {"type": "boolean"},
2024
+ },
2025
+ {
2026
+ "name": "has_final_answer_guardrail",
2027
+ "in": "query",
2028
+ "required": False,
2029
+ "description": (
2030
+ "Filter summary by whether compact summaries contain "
2031
+ "an applied final-answer guardrail"
2032
+ ),
2033
+ "schema": {"type": "boolean"},
2034
+ },
2035
+ {
2036
+ "name": "has_llm_provider_retries",
2037
+ "in": "query",
2038
+ "required": False,
2039
+ "description": (
2040
+ "Filter summary by whether compact LLM provider "
2041
+ "diagnostics recorded retries"
2042
+ ),
2043
+ "schema": {"type": "boolean"},
2044
+ },
2045
+ {
2046
+ "name": "final_answer_guardrail_reason",
2047
+ "in": "query",
2048
+ "required": False,
2049
+ "description": (
2050
+ "Filter summary by applied final-answer guardrail "
2051
+ "reason"
2052
+ ),
2053
+ "schema": {"type": "string", "minLength": 1},
2054
+ },
2055
+ ],
2056
+ "responses": {
2057
+ "200": _json_response(
2058
+ "Runtime run fleet summary",
2059
+ "RuntimeRunSummaryResponse",
2060
+ ),
2061
+ "400": _error_response("Runtime trace persistence is not configured"),
2062
+ "401": _error_response("Missing or invalid bearer token"),
2063
+ },
2064
+ }
2065
+ },
2066
+ },
2067
+ }
2068
+
2069
+
2070
+ def _trace_permission_policy_properties() -> Dict[str, Dict[str, str]]:
2071
+ return {
2072
+ "trace_directory_permissions": {"type": "string", "const": "0700"},
2073
+ "trace_file_permissions": {"type": "string", "const": "0600"},
2074
+ "trace_probe_file_permissions": {"type": "string", "const": "0600"},
2075
+ }
2076
+
2077
+
2078
+ def _llm_provider_audit_properties() -> Dict[str, Dict[str, Any]]:
2079
+ return {
2080
+ "llm_provider": {
2081
+ "type": "string",
2082
+ "enum": [
2083
+ "openai_compatible",
2084
+ "deepseek",
2085
+ "qwen_openai_compatible",
2086
+ "ollama_openai_compatible",
2087
+ "unconfigured",
2088
+ ],
2089
+ },
2090
+ "llm_provider_display_name": {"type": "string"},
2091
+ "llm_base_url": {"type": "string"},
2092
+ "llm_base_url_configured": {
2093
+ "type": "string",
2094
+ "enum": ["true", "false"],
2095
+ },
2096
+ "llm_model": {"type": "string"},
2097
+ "llm_api_key_configured": {
2098
+ "type": "string",
2099
+ "enum": ["true", "false"],
2100
+ },
2101
+ "llm_timeout_seconds": {"type": "string"},
2102
+ "llm_max_retries": {"type": "string"},
2103
+ "llm_retry_backoff_seconds": {"type": "string"},
2104
+ }
2105
+
2106
+
2107
+ def _embedding_provider_audit_properties() -> Dict[str, Dict[str, Any]]:
2108
+ return {
2109
+ "embedding_provider": {
2110
+ "type": "string",
2111
+ "enum": ["openai_compatible", "unconfigured"],
2112
+ },
2113
+ "embedding_base_url": {"type": "string"},
2114
+ "embedding_base_url_configured": {
2115
+ "type": "string",
2116
+ "enum": ["true", "false"],
2117
+ },
2118
+ "embedding_model": {"type": "string"},
2119
+ "embedding_api_key_configured": {
2120
+ "type": "string",
2121
+ "enum": ["true", "false"],
2122
+ },
2123
+ "embedding_timeout_seconds": {"type": "string"},
2124
+ "embedding_max_retries": {"type": "string"},
2125
+ "embedding_retry_backoff_seconds": {"type": "string"},
2126
+ }
2127
+
2128
+
2129
+ def _diagnostic_audit_properties() -> Dict[str, Dict[str, Any]]:
2130
+ properties: Dict[str, Dict[str, Any]] = {
2131
+ "auth_subject_count": {"type": "string"},
2132
+ "idempotency_cache_backend": {"type": "string", "enum": ["memory", "sqlite"]},
2133
+ "idempotency_cache_path_configured": {"type": "string", "enum": ["true", "false"]},
2134
+ "runtime_allowed_tools": {"type": "string"},
2135
+ "runtime_allowed_tools_by_subject_count": {"type": "string"},
2136
+ "runtime_pending_approval_stale_seconds": {"type": "string"},
2137
+ "runtime_instance_heartbeat_seconds": {"type": "string"},
2138
+ "runtime_orphaned_run_stale_seconds": {"type": "string"},
2139
+ }
2140
+ properties.update(_trace_permission_policy_properties())
2141
+ properties.update(_embedding_provider_audit_properties())
2142
+ properties.update(_llm_provider_audit_properties())
2143
+ return properties
2144
+
2145
+
2146
+ def _runtime_llm_provider_metric_properties() -> Dict[str, Dict[str, Any]]:
2147
+ string_metric_schema = {"type": "string"}
2148
+ map_metric_schema = {
2149
+ "type": "object",
2150
+ "additionalProperties": {"type": "string"},
2151
+ }
2152
+ properties = {
2153
+ "runtime_llm_provider_requests_total": string_metric_schema,
2154
+ "runtime_llm_provider_request_attempts_total": string_metric_schema,
2155
+ "runtime_llm_provider_request_retries_total": string_metric_schema,
2156
+ "runtime_llm_provider_request_duration_seconds_count": string_metric_schema,
2157
+ "runtime_llm_provider_request_duration_seconds_sum": string_metric_schema,
2158
+ "average_runtime_llm_provider_request_duration_seconds": string_metric_schema,
2159
+ "max_runtime_llm_provider_request_duration_seconds": string_metric_schema,
2160
+ "runtime_llm_provider_requests_by_status": map_metric_schema,
2161
+ "runtime_llm_provider_request_errors_by_type": map_metric_schema,
2162
+ "runtime_llm_provider_request_http_status": map_metric_schema,
2163
+ "runtime_llm_provider_request_retryable_reason": map_metric_schema,
2164
+ "runtime_llm_provider_request_duration_seconds_bucket": map_metric_schema,
2165
+ }
2166
+ return properties
2167
+
2168
+
2169
+ def _metrics_response_properties() -> Dict[str, Dict[str, Any]]:
2170
+ properties = _diagnostic_audit_properties()
2171
+ properties["runtime_progress_event_sink_failures_total"] = {"type": "string"}
2172
+ properties["runtime_hook_failures_total"] = {"type": "string"}
2173
+ properties["runtime_reconciliation_runs_total"] = {"type": "string"}
2174
+ properties["runtime_reconciliation_runs_by_status"] = {
2175
+ "type": "object",
2176
+ "additionalProperties": {"type": "string"},
2177
+ }
2178
+ properties["runtime_reconciliation_traces_scanned_total"] = {"type": "string"}
2179
+ properties["runtime_reconciliation_outcomes"] = {
2180
+ "type": "object",
2181
+ "additionalProperties": {"type": "string"},
2182
+ }
2183
+ properties["runtime_reconciliation_errors_total"] = {"type": "string"}
2184
+ properties.update(_runtime_llm_provider_metric_properties())
2185
+ return properties
2186
+
2187
+
2188
+ def _json_response(
2189
+ description: str,
2190
+ schema_name: str,
2191
+ *,
2192
+ headers: Optional[Dict[str, Any]] = None,
2193
+ ) -> Dict[str, Any]:
2194
+ response = {
2195
+ "description": description,
2196
+ "content": {
2197
+ "application/json": {
2198
+ "schema": {"$ref": f"#/components/schemas/{schema_name}"},
2199
+ }
2200
+ },
2201
+ }
2202
+ response["headers"] = _response_headers(headers)
2203
+ return response
2204
+
2205
+
2206
+ def _object_response(description: str) -> Dict[str, Any]:
2207
+ return {
2208
+ "description": description,
2209
+ "headers": _response_headers(),
2210
+ "content": {
2211
+ "application/json": {
2212
+ "schema": {"type": "object"},
2213
+ }
2214
+ },
2215
+ }
2216
+
2217
+
2218
+ def _text_response(description: str) -> Dict[str, Any]:
2219
+ return {
2220
+ "description": description,
2221
+ "headers": _response_headers(),
2222
+ "content": {
2223
+ "text/plain": {
2224
+ "schema": {"type": "string"},
2225
+ }
2226
+ },
2227
+ }
2228
+
2229
+
2230
+ def _empty_response(description: str) -> Dict[str, Any]:
2231
+ return {
2232
+ "description": description,
2233
+ "headers": _response_headers(),
2234
+ }
2235
+
2236
+
2237
+ def _runtime_run_status_properties(
2238
+ *,
2239
+ include_pending_approval: bool,
2240
+ include_steps: bool = True,
2241
+ ) -> Dict[str, Any]:
2242
+ properties = {
2243
+ "trace_type": {
2244
+ "type": "string",
2245
+ "const": RUNTIME_TRACE_TYPE,
2246
+ },
2247
+ "runtime_engine": {
2248
+ "type": "string",
2249
+ "enum": ["langgraph"],
2250
+ },
2251
+ "run_id": {"type": "string"},
2252
+ "status": {
2253
+ "type": "string",
2254
+ "enum": [
2255
+ "cancelled",
2256
+ "done",
2257
+ "failed",
2258
+ "requires_approval",
2259
+ "resumed",
2260
+ "resuming",
2261
+ "running",
2262
+ ],
2263
+ },
2264
+ "lifecycle_state": {
2265
+ "type": "string",
2266
+ "enum": [
2267
+ "cancelled",
2268
+ "failed",
2269
+ "planning",
2270
+ "running",
2271
+ "succeeded",
2272
+ "unknown",
2273
+ "waiting_approval",
2274
+ ],
2275
+ },
2276
+ "goal": {"type": "string"},
2277
+ "auth_subject": {"type": "string"},
2278
+ "resumed_by_auth_subject": {"type": "string"},
2279
+ "approved_by_auth_subject": {"type": "string"},
2280
+ "approved_at": {"type": "string"},
2281
+ "metadata": {
2282
+ "type": "object",
2283
+ "additionalProperties": {"type": "string"},
2284
+ },
2285
+ "metadata_keys": {
2286
+ "type": "array",
2287
+ "items": {"type": "string"},
2288
+ },
2289
+ "tags": {
2290
+ "type": "array",
2291
+ "items": {"type": "string"},
2292
+ },
2293
+ "answer": {"type": "string"},
2294
+ "final_answer_guardrail": _final_answer_guardrail_schema(),
2295
+ "trace_path": {"type": "string"},
2296
+ "iteration_count": {"type": "string"},
2297
+ "max_iterations": {"type": "string"},
2298
+ "iteration_budget_remaining": {"type": "string"},
2299
+ "plan_count": {"type": "string"},
2300
+ "step_count": {"type": "string"},
2301
+ "observation_count": {"type": "string"},
2302
+ "event_count": {"type": "string"},
2303
+ "progress_event_count": {"type": "string"},
2304
+ "graph_phase_count": {"type": "string"},
2305
+ "progress_event_sink_failure_count": {"type": "string"},
2306
+ "hook_failure_count": {"type": "string"},
2307
+ "llm_provider_request_status": {"type": "string"},
2308
+ "llm_provider_request_attempt_count": {"type": "string"},
2309
+ "llm_provider_request_retry_count": {"type": "string"},
2310
+ "llm_provider_request_error_type": {"type": "string"},
2311
+ "llm_provider_request_http_status": {"type": "string"},
2312
+ "llm_provider_request_retryable_reason": {"type": "string"},
2313
+ "llm_provider_request_duration_seconds": {"type": "string"},
2314
+ "failed_observation_count": {"type": "string"},
2315
+ "planner_failure_count": {"type": "string"},
2316
+ "tool_failure_count": {"type": "string"},
2317
+ "approval_required_count": {"type": "string"},
2318
+ "latest_failed_action_id": {"type": "string"},
2319
+ "latest_failed_tool": {"type": "string"},
2320
+ "latest_failed_error_code": {"type": "string"},
2321
+ "approved_action_count": {"type": "string"},
2322
+ "approved_action_ids": {
2323
+ "type": "array",
2324
+ "items": {"type": "string"},
2325
+ },
2326
+ "approved_tool_counts": {
2327
+ "type": "object",
2328
+ "additionalProperties": {"type": "string"},
2329
+ },
2330
+ "error_code_counts": {
2331
+ "type": "object",
2332
+ "additionalProperties": {"type": "string"},
2333
+ },
2334
+ "latest_plan_action_count": {"type": "string"},
2335
+ "latest_plan_action_ids": {
2336
+ "type": "array",
2337
+ "items": {"type": "string"},
2338
+ },
2339
+ "dependency_edge_count": {"type": "string"},
2340
+ "tool_names": {
2341
+ "type": "array",
2342
+ "items": {"type": "string"},
2343
+ },
2344
+ "artifact_count": {"type": "string"},
2345
+ "artifact_ids": {
2346
+ "type": "array",
2347
+ "items": {"type": "string"},
2348
+ },
2349
+ "artifact_kinds": {
2350
+ "type": "array",
2351
+ "items": {"type": "string"},
2352
+ },
2353
+ "artifact_formats": {
2354
+ "type": "array",
2355
+ "items": {"type": "string"},
2356
+ },
2357
+ "artifact_tags": {
2358
+ "type": "array",
2359
+ "items": {"type": "string"},
2360
+ },
2361
+ "artifact_total_bytes": {"type": "string"},
2362
+ "artifact_bytes_by_kind": {
2363
+ "type": "object",
2364
+ "additionalProperties": {"type": "string"},
2365
+ },
2366
+ "pending_approval_action_id": {"type": "string"},
2367
+ "pending_approval_tool": {"type": "string"},
2368
+ "resumed_from_run_id": {"type": "string"},
2369
+ "resumed_to_run_id": {"type": "string"},
2370
+ "cancelled_at": {"type": "string"},
2371
+ "cancelled_by_auth_subject": {"type": "string"},
2372
+ "cancel_reason": {"type": "string"},
2373
+ "started_at": {"type": "string"},
2374
+ "completed_at": {"type": "string"},
2375
+ "duration_seconds": {
2376
+ "type": "string",
2377
+ "pattern": r"^\d+\.\d{4}$",
2378
+ },
2379
+ "error_code": {"type": "string"},
2380
+ "error": {"type": "string"},
2381
+ }
2382
+ if include_pending_approval:
2383
+ properties["pending_approval"] = _pending_approval_schema()
2384
+ if include_steps:
2385
+ properties["steps"] = {
2386
+ "type": "array",
2387
+ "items": {"$ref": "#/components/schemas/RuntimeStep"},
2388
+ }
2389
+ return properties
2390
+
2391
+
2392
+ def _pending_approval_schema() -> Dict[str, Any]:
2393
+ return {
2394
+ "type": "object",
2395
+ "properties": {
2396
+ "id": {"type": "string"},
2397
+ "tool": {"type": "string"},
2398
+ "input": {"type": "object"},
2399
+ "reason": {"type": "string"},
2400
+ },
2401
+ "required": ["id", "tool", "input"],
2402
+ "additionalProperties": False,
2403
+ }
2404
+
2405
+
2406
+ def _runtime_artifact_list_item_schema() -> Dict[str, Any]:
2407
+ return {
2408
+ "type": "object",
2409
+ "required": [
2410
+ "artifact_id",
2411
+ "action_id",
2412
+ "tool",
2413
+ "title",
2414
+ "kind",
2415
+ "format",
2416
+ "tags",
2417
+ "bytes",
2418
+ ],
2419
+ "properties": {
2420
+ "artifact_id": {"type": "string"},
2421
+ "action_id": {"type": "string"},
2422
+ "tool": {"type": "string"},
2423
+ "title": {"type": "string"},
2424
+ "kind": {"type": "string"},
2425
+ "format": {"type": "string"},
2426
+ "tags": {"type": "array", "items": {"type": "string"}},
2427
+ "bytes": {"type": "string"},
2428
+ },
2429
+ "additionalProperties": False,
2430
+ }
2431
+
2432
+
2433
+ def _runtime_artifact_detail_schema() -> Dict[str, Any]:
2434
+ return {
2435
+ "type": "object",
2436
+ "required": [
2437
+ "artifact_id",
2438
+ "title",
2439
+ "kind",
2440
+ "format",
2441
+ "content",
2442
+ "tags",
2443
+ "bytes",
2444
+ ],
2445
+ "properties": {
2446
+ "artifact_id": {"type": "string"},
2447
+ "title": {"type": "string"},
2448
+ "kind": {"type": "string"},
2449
+ "format": {"type": "string"},
2450
+ "content": {"type": "string"},
2451
+ "tags": {"type": "array", "items": {"type": "string"}},
2452
+ "bytes": {
2453
+ "oneOf": [
2454
+ {"type": "integer", "minimum": 0},
2455
+ {"type": "string"},
2456
+ ]
2457
+ },
2458
+ },
2459
+ "additionalProperties": False,
2460
+ }
2461
+
2462
+
2463
+ def _runtime_approval_queue_item_schema() -> Dict[str, Any]:
2464
+ return {
2465
+ "type": "object",
2466
+ "required": [
2467
+ "run_id",
2468
+ "status",
2469
+ "goal",
2470
+ "auth_subject",
2471
+ "trace_path",
2472
+ "pending_approval_action_id",
2473
+ "pending_approval_tool",
2474
+ ],
2475
+ "properties": {
2476
+ "run_id": {"type": "string"},
2477
+ "status": {"type": "string"},
2478
+ "goal": {"type": "string"},
2479
+ "auth_subject": {"type": "string"},
2480
+ "trace_path": {"type": "string"},
2481
+ "pending_approval_action_id": {"type": "string"},
2482
+ "pending_approval_tool": {"type": "string"},
2483
+ "started_at": {"type": "string"},
2484
+ "duration_seconds": {"type": "string"},
2485
+ "pending_age_seconds": {"type": "string"},
2486
+ },
2487
+ "additionalProperties": False,
2488
+ }
2489
+
2490
+
2491
+ def _final_answer_guardrail_schema() -> Dict[str, Any]:
2492
+ return {
2493
+ "type": "object",
2494
+ "properties": {
2495
+ "applied": {"type": "string", "enum": ["true"]},
2496
+ "reason": {
2497
+ "type": "string",
2498
+ "enum": [
2499
+ "runtime_identity_boundary",
2500
+ "runtime_deployment_boundary",
2501
+ "unresolved_failure_boundary",
2502
+ ],
2503
+ },
2504
+ "original_answer_omitted": {"type": "string", "enum": ["true"]},
2505
+ },
2506
+ "additionalProperties": False,
2507
+ }
2508
+
2509
+
2510
+ def _llm_provider_request_schema() -> Dict[str, Any]:
2511
+ return {
2512
+ "type": "object",
2513
+ "properties": {
2514
+ "attempt_count": {"type": "string"},
2515
+ "retry_count": {"type": "string"},
2516
+ "status": {"type": "string", "enum": ["ok", "failed"]},
2517
+ "stream": {"type": "string", "enum": ["true", "false"]},
2518
+ "duration_seconds": {"type": "string", "pattern": r"^\d+\.\d{4}$"},
2519
+ "error_type": {"type": "string"},
2520
+ "http_status": {"type": "string"},
2521
+ "retryable_reason": {"type": "string"},
2522
+ },
2523
+ "additionalProperties": False,
2524
+ }
2525
+
2526
+
2527
+ def _error_response(
2528
+ description: str,
2529
+ *,
2530
+ headers: Optional[Dict[str, Any]] = None,
2531
+ ) -> Dict[str, Any]:
2532
+ return {
2533
+ "description": description,
2534
+ "headers": _response_headers(headers),
2535
+ "content": {
2536
+ "application/json": {
2537
+ "schema": {"$ref": "#/components/schemas/ErrorResponse"},
2538
+ }
2539
+ },
2540
+ }
2541
+
2542
+
2543
+ def _response_headers(headers: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
2544
+ merged = dict(COMMON_RESPONSE_HEADERS)
2545
+ if headers:
2546
+ merged.update(headers)
2547
+ return merged
2548
+
2549
+
2550
+ def _idempotency_key_parameter() -> Dict[str, Any]:
2551
+ return {
2552
+ "name": "Idempotency-Key",
2553
+ "in": "header",
2554
+ "required": False,
2555
+ "description": (
2556
+ "Optional retry key scoped to this execution route and resource when "
2557
+ "applicable; must be printable ASCII."
2558
+ ),
2559
+ "schema": {"type": "string", "maxLength": 128},
2560
+ }
2561
+
2562
+
2563
+ def _diagnostic_security() -> list[Dict[str, list[str]]]:
2564
+ return [{"BearerAuth": []}, {}]
2565
+
2566
+
2567
+ def _diagnostic_description() -> str:
2568
+ return (
2569
+ "May require bearer authentication when runtime diagnostic protection "
2570
+ "is enabled."
2571
+ )