ithrl 0.1.0__py3-none-any.whl

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 (108) hide show
  1. ithrl/__init__.py +1 -0
  2. ithrl/__main__.py +6 -0
  3. ithrl/adapters/__init__.py +49 -0
  4. ithrl/adapters/_jsonl.py +266 -0
  5. ithrl/adapters/codex/__init__.py +5 -0
  6. ithrl/adapters/codex/context.py +204 -0
  7. ithrl/adapters/codex/decisions.py +224 -0
  8. ithrl/adapters/codex/discovery.py +60 -0
  9. ithrl/adapters/codex/parser.py +191 -0
  10. ithrl/adapters/contracts.py +106 -0
  11. ithrl/adapters/copilot/__init__.py +5 -0
  12. ithrl/adapters/copilot/context.py +182 -0
  13. ithrl/adapters/copilot/decisions.py +294 -0
  14. ithrl/adapters/copilot/discovery.py +28 -0
  15. ithrl/adapters/copilot/parser.py +283 -0
  16. ithrl/adapters/discovery.py +220 -0
  17. ithrl/adapters/errors.py +52 -0
  18. ithrl/adapters/registry.py +433 -0
  19. ithrl/behavior.py +138 -0
  20. ithrl/calibration.py +434 -0
  21. ithrl/case/__init__.py +33 -0
  22. ithrl/case/contracts.py +88 -0
  23. ithrl/case/evidence.py +169 -0
  24. ithrl/case/filesystem.py +340 -0
  25. ithrl/case/source.py +208 -0
  26. ithrl/case/source_context.py +119 -0
  27. ithrl/case/source_storage.py +234 -0
  28. ithrl/case/storage.py +377 -0
  29. ithrl/cli/__init__.py +968 -0
  30. ithrl/cli/extract.py +478 -0
  31. ithrl/cli/native.py +484 -0
  32. ithrl/cli/output.py +786 -0
  33. ithrl/cli/paths.py +24 -0
  34. ithrl/cli/sampled.py +485 -0
  35. ithrl/cli/sampled_output.py +472 -0
  36. ithrl/cli/sampled_reduction.py +1036 -0
  37. ithrl/cli/sampled_session.py +342 -0
  38. ithrl/cli/shrink.py +523 -0
  39. ithrl/context.py +465 -0
  40. ithrl/decisions.py +271 -0
  41. ithrl/examples/synthetic-trace.json +46 -0
  42. ithrl/execution/__init__.py +68 -0
  43. ithrl/execution/budget.py +146 -0
  44. ithrl/execution/contracts.py +426 -0
  45. ithrl/execution/preflight.py +346 -0
  46. ithrl/experiment.py +453 -0
  47. ithrl/extraction.py +206 -0
  48. ithrl/measurement.py +315 -0
  49. ithrl/observations.py +1148 -0
  50. ithrl/path_safety.py +100 -0
  51. ithrl/reduce/__init__.py +53 -0
  52. ithrl/reduce/contracts.py +508 -0
  53. ithrl/reduce/engine.py +901 -0
  54. ithrl/reduce/search.py +178 -0
  55. ithrl/results/__init__.py +49 -0
  56. ithrl/results/models.py +294 -0
  57. ithrl/results/storage.py +485 -0
  58. ithrl/results/summary.py +420 -0
  59. ithrl/results/validation.py +611 -0
  60. ithrl/run_state.py +1135 -0
  61. ithrl/runner/__init__.py +44 -0
  62. ithrl/runner/codex/__init__.py +17 -0
  63. ithrl/runner/codex/capability.py +708 -0
  64. ithrl/runner/codex/configuration.py +529 -0
  65. ithrl/runner/codex/isolation.py +396 -0
  66. ithrl/runner/codex/materialize.py +358 -0
  67. ithrl/runner/codex/policy.py +67 -0
  68. ithrl/runner/codex/protocol.py +649 -0
  69. ithrl/runner/codex/protocol_contracts.py +171 -0
  70. ithrl/runner/codex/runner.py +533 -0
  71. ithrl/runner/codex/runtime_configuration.py +264 -0
  72. ithrl/runner/codex/schema.py +527 -0
  73. ithrl/runner/codex/transcript.py +130 -0
  74. ithrl/runner/codex/worker.py +175 -0
  75. ithrl/runner/contracts.py +419 -0
  76. ithrl/runner/copilot/__init__.py +18 -0
  77. ithrl/runner/copilot/capability.py +825 -0
  78. ithrl/runner/copilot/configuration.py +201 -0
  79. ithrl/runner/copilot/isolation.py +374 -0
  80. ithrl/runner/copilot/materialize.py +484 -0
  81. ithrl/runner/copilot/policy.py +110 -0
  82. ithrl/runner/copilot/protocol/__init__.py +18 -0
  83. ithrl/runner/copilot/protocol/contracts.py +74 -0
  84. ithrl/runner/copilot/protocol/decoding.py +93 -0
  85. ithrl/runner/copilot/protocol/parser.py +418 -0
  86. ithrl/runner/copilot/protocol/state.py +130 -0
  87. ithrl/runner/copilot/runner.py +425 -0
  88. ithrl/runner/copilot/worker.py +351 -0
  89. ithrl/runner/evidence.py +345 -0
  90. ithrl/runner/fake.py +107 -0
  91. ithrl/runner/registry.py +90 -0
  92. ithrl/runner/runtime/__init__.py +50 -0
  93. ithrl/runner/runtime/contracts.py +157 -0
  94. ithrl/runner/runtime/output.py +184 -0
  95. ithrl/runner/runtime/process.py +954 -0
  96. ithrl/runner/runtime/protection.py +562 -0
  97. ithrl/runner/runtime/state.py +282 -0
  98. ithrl/runner/validation.py +376 -0
  99. ithrl/sampling.py +412 -0
  100. ithrl/statistics.py +276 -0
  101. ithrl/synthetic.py +511 -0
  102. ithrl/timestamps.py +26 -0
  103. ithrl/workflow.py +570 -0
  104. ithrl-0.1.0.dist-info/METADATA +118 -0
  105. ithrl-0.1.0.dist-info/RECORD +108 -0
  106. ithrl-0.1.0.dist-info/WHEEL +4 -0
  107. ithrl-0.1.0.dist-info/entry_points.txt +2 -0
  108. ithrl-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,527 @@
1
+ """Verify the Codex app-server schema used by the final-response runner."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import os
8
+ import stat
9
+ from importlib.metadata import version as distribution_version
10
+ from pathlib import Path
11
+ from typing import cast
12
+
13
+ from jsonschema import Draft7Validator
14
+ from jsonschema.exceptions import SchemaError
15
+ from jsonschema.validators import validator_for
16
+
17
+ from ithrl.context import JsonObject
18
+ from ithrl.runner.codex.protocol import (
19
+ ACTION_ITEM_TYPES,
20
+ ACTION_REQUEST_METHODS,
21
+ PASSIVE_ITEM_TYPES,
22
+ )
23
+
24
+ _MAX_SCHEMA_BYTES = 2 * 1024 * 1024
25
+ _SCHEMA_FILES = (
26
+ "ClientRequest.json",
27
+ "CommandExecutionRequestApprovalResponse.json",
28
+ "DynamicToolCallResponse.json",
29
+ "FileChangeRequestApprovalResponse.json",
30
+ "McpServerElicitationRequestResponse.json",
31
+ "ServerNotification.json",
32
+ "ServerRequest.json",
33
+ "v1/InitializeResponse.json",
34
+ "v2/ThreadStartResponse.json",
35
+ "v2/TurnStartResponse.json",
36
+ )
37
+ _CLIENT_METHODS = frozenset({"initialize", "thread/inject_items", "thread/start", "turn/start"})
38
+ _NOTIFICATION_METHODS = frozenset(
39
+ {
40
+ "account/rateLimits/updated",
41
+ "item/agentMessage/delta",
42
+ "item/completed",
43
+ "item/plan/delta",
44
+ "item/reasoning/summaryPartAdded",
45
+ "item/reasoning/summaryTextDelta",
46
+ "item/reasoning/textDelta",
47
+ "item/started",
48
+ "model/rerouted",
49
+ "model/verification",
50
+ "thread/started",
51
+ "thread/status/changed",
52
+ "thread/tokenUsage/updated",
53
+ "turn/completed",
54
+ "turn/started",
55
+ }
56
+ )
57
+ _KNOWN_THREAD_ITEMS = ACTION_ITEM_TYPES | PASSIVE_ITEM_TYPES
58
+
59
+
60
+ class CodexSchemaError(RuntimeError):
61
+ """The installed app-server protocol does not satisfy the runner contract."""
62
+
63
+
64
+ def verify_schema_bundle(root: Path) -> str:
65
+ """Return a digest when the generated app-server schema is supported."""
66
+
67
+ documents, digest = _read_bundle(root)
68
+ client = documents["ClientRequest.json"]
69
+ notifications = documents["ServerNotification.json"]
70
+ requests = documents["ServerRequest.json"]
71
+
72
+ client_methods = _require_methods(client, _CLIENT_METHODS)
73
+ notification_methods = _require_methods(notifications, _NOTIFICATION_METHODS)
74
+ if not set(_method_definitions(requests)) >= ACTION_REQUEST_METHODS:
75
+ raise CodexSchemaError("Codex app-server action requests are not supported")
76
+
77
+ _verify_client_contract(client, client_methods)
78
+ _verify_notification_contract(notifications, notification_methods)
79
+ _verify_response_contract(documents)
80
+ return digest
81
+
82
+
83
+ def _read_bundle(root: Path) -> tuple[dict[str, dict[str, object]], str]:
84
+ documents: dict[str, dict[str, object]] = {}
85
+ digest = hashlib.sha256()
86
+ for relative in _SCHEMA_FILES:
87
+ try:
88
+ raw = _read_schema(root / relative)
89
+ except OSError as error:
90
+ raise CodexSchemaError("Codex app-server schema bundle is incomplete") from error
91
+ try:
92
+ value = json.loads(raw)
93
+ except (UnicodeDecodeError, json.JSONDecodeError) as error:
94
+ raise CodexSchemaError(
95
+ "Codex app-server schema bundle contains invalid JSON"
96
+ ) from error
97
+ if not isinstance(value, dict):
98
+ raise CodexSchemaError("Codex app-server schema bundle has an invalid document")
99
+ documents[relative] = cast(dict[str, object], value)
100
+ digest.update(relative.encode("utf-8"))
101
+ digest.update(b"\0")
102
+ digest.update(raw)
103
+ digest.update(b"\0")
104
+ return documents, digest.hexdigest()
105
+
106
+
107
+ def _read_schema(path: Path) -> bytes:
108
+ metadata = path.lstat()
109
+ if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
110
+ raise OSError("unsafe schema file")
111
+ if metadata.st_size < 1 or metadata.st_size > _MAX_SCHEMA_BYTES:
112
+ raise OSError("schema file exceeds its size bound")
113
+ with path.open("rb") as stream:
114
+ opened = os.fstat(stream.fileno())
115
+ if (opened.st_dev, opened.st_ino) != (metadata.st_dev, metadata.st_ino):
116
+ raise OSError("schema file changed while opening")
117
+ raw = stream.read(_MAX_SCHEMA_BYTES + 1)
118
+ if len(raw) != metadata.st_size:
119
+ raise OSError("schema file changed while reading")
120
+ return raw
121
+
122
+
123
+ def _verify_client_contract(
124
+ schema: dict[str, object],
125
+ methods: dict[str, str],
126
+ ) -> None:
127
+ required = {
128
+ "initialize": {"capabilities", "clientInfo"},
129
+ "thread/inject_items": {"items", "threadId"},
130
+ "thread/start": {
131
+ "approvalPolicy",
132
+ "approvalsReviewer",
133
+ "baseInstructions",
134
+ "cwd",
135
+ "developerInstructions",
136
+ "ephemeral",
137
+ "model",
138
+ "modelProvider",
139
+ "sandbox",
140
+ },
141
+ "turn/start": {
142
+ "approvalPolicy",
143
+ "approvalsReviewer",
144
+ "cwd",
145
+ "effort",
146
+ "input",
147
+ "model",
148
+ "personality",
149
+ "sandboxPolicy",
150
+ "threadId",
151
+ "toolOutput",
152
+ },
153
+ }
154
+ for method, properties in required.items():
155
+ _require_properties(_definition(schema, methods[method]), properties, method)
156
+ thread_start = _definition(schema, methods["thread/start"])
157
+ turn_start = _definition(schema, methods["turn/start"])
158
+ for params in (thread_start, turn_start):
159
+ _require_nullable_reference(params, "approvalPolicy", "AskForApproval")
160
+ _require_nullable_reference(params, "approvalsReviewer", "ApprovalsReviewer")
161
+ _require_nullable_reference(thread_start, "sandbox", "SandboxMode")
162
+ _require_nullable_reference(turn_start, "sandboxPolicy", "SandboxPolicy")
163
+ if not _supports_string_enum_value(_definition(schema, "AskForApproval"), "never"):
164
+ raise CodexSchemaError("Codex app-server cannot enforce no-approval execution")
165
+ if not _supports_string_enum_value(_definition(schema, "ApprovalsReviewer"), "user"):
166
+ raise CodexSchemaError("Codex app-server has no supported approval reviewer")
167
+ if not _supports_string_enum_value(_definition(schema, "SandboxMode"), "read-only"):
168
+ raise CodexSchemaError("Codex app-server has no read-only thread sandbox")
169
+ sandbox = _definition(schema, "SandboxPolicy")
170
+ read_only = _tagged_variant(sandbox, "readOnly")
171
+ if read_only is None or _property(read_only, "networkAccess").get("type") != "boolean":
172
+ raise CodexSchemaError("Codex app-server has no supported turn sandbox policy")
173
+ try:
174
+ validator_class = validator_for(schema, default=Draft7Validator)
175
+ validator_class.check_schema(schema)
176
+ validator = validator_class(schema)
177
+ except SchemaError as error:
178
+ raise CodexSchemaError("Codex app-server client request schema is invalid") from error
179
+ for method, params in _client_request_samples():
180
+ request: JsonObject = {"id": 1, "method": method, "params": params}
181
+ if not validator.is_valid(request):
182
+ raise CodexSchemaError(f"Codex app-server {method} request shape is unsupported")
183
+
184
+
185
+ def _client_request_samples() -> list[tuple[str, JsonObject]]:
186
+ """Return every materially distinct request form emitted by the worker."""
187
+
188
+ samples: list[tuple[str, JsonObject]] = [
189
+ (
190
+ "initialize",
191
+ {
192
+ "capabilities": {"experimentalApi": False},
193
+ "clientInfo": {
194
+ "name": "ithrl",
195
+ "title": "ithrl",
196
+ "version": distribution_version("ithrl"),
197
+ },
198
+ },
199
+ ),
200
+ (
201
+ "thread/inject_items",
202
+ {"threadId": "thread", "items": [{"type": "message"}]},
203
+ ),
204
+ ]
205
+
206
+ thread_start: JsonObject = {
207
+ "approvalPolicy": "never",
208
+ "approvalsReviewer": "user",
209
+ "cwd": "/tmp/ithrl-state/workspace", # noqa: S108 - schema sample
210
+ "ephemeral": True,
211
+ "model": "model",
212
+ "modelProvider": "ithrl",
213
+ "sandbox": "read-only",
214
+ }
215
+ instruction_variants: tuple[JsonObject, ...] = (
216
+ {},
217
+ {"baseInstructions": "instructions"},
218
+ {"developerInstructions": "instructions"},
219
+ {
220
+ "baseInstructions": "instructions",
221
+ "developerInstructions": "instructions",
222
+ },
223
+ )
224
+ samples.extend(
225
+ ("thread/start", {**thread_start, **instructions}) for instructions in instruction_variants
226
+ )
227
+
228
+ turn_start: JsonObject = {
229
+ "approvalPolicy": "never",
230
+ "approvalsReviewer": "user",
231
+ "cwd": "/tmp/ithrl-state/workspace", # noqa: S108 - schema sample
232
+ "model": "model",
233
+ "sandboxPolicy": {"type": "readOnly", "networkAccess": False},
234
+ "threadId": "thread",
235
+ }
236
+ setting_variants: tuple[JsonObject, ...] = (
237
+ {},
238
+ {"effort": "low"},
239
+ {"personality": "none"},
240
+ {"effort": "low", "personality": "none"},
241
+ )
242
+ trigger_variants: tuple[JsonObject, ...] = (
243
+ {"input": [{"type": "text", "text": "input"}]},
244
+ {
245
+ "input": [],
246
+ "toolOutput": {"name": "tool", "namespace": None, "output": "output"},
247
+ },
248
+ {
249
+ "input": [],
250
+ "toolOutput": {
251
+ "name": "tool",
252
+ "namespace": None,
253
+ "output": [{"type": "input_text", "text": "output"}],
254
+ },
255
+ },
256
+ )
257
+ samples.extend(
258
+ ("turn/start", {**turn_start, **settings, **trigger})
259
+ for settings in setting_variants
260
+ for trigger in trigger_variants
261
+ )
262
+ return samples
263
+
264
+
265
+ def _verify_notification_contract(
266
+ schema: dict[str, object],
267
+ methods: dict[str, str],
268
+ ) -> None:
269
+ required = {
270
+ "account/rateLimits/updated": {"rateLimits"},
271
+ "item/agentMessage/delta": {"delta", "itemId", "threadId", "turnId"},
272
+ "item/completed": {"item", "threadId", "turnId"},
273
+ "item/started": {"item", "threadId", "turnId"},
274
+ "model/rerouted": {
275
+ "fromModel",
276
+ "reason",
277
+ "threadId",
278
+ "toModel",
279
+ "turnId",
280
+ },
281
+ "model/verification": {"threadId", "turnId", "verifications"},
282
+ "item/plan/delta": {"delta", "itemId", "threadId", "turnId"},
283
+ "item/reasoning/summaryPartAdded": {
284
+ "itemId",
285
+ "summaryIndex",
286
+ "threadId",
287
+ "turnId",
288
+ },
289
+ "item/reasoning/summaryTextDelta": {
290
+ "delta",
291
+ "itemId",
292
+ "summaryIndex",
293
+ "threadId",
294
+ "turnId",
295
+ },
296
+ "item/reasoning/textDelta": {
297
+ "contentIndex",
298
+ "delta",
299
+ "itemId",
300
+ "threadId",
301
+ "turnId",
302
+ },
303
+ "thread/tokenUsage/updated": {"threadId", "tokenUsage", "turnId"},
304
+ "thread/started": {"thread"},
305
+ "thread/status/changed": {"status", "threadId"},
306
+ "turn/completed": {"threadId", "turn"},
307
+ "turn/started": {"threadId", "turn"},
308
+ }
309
+ for method, properties in required.items():
310
+ _require_properties(_definition(schema, methods[method]), properties, method)
311
+
312
+ completed = _definition(schema, methods["item/completed"])
313
+ thread_item = _referenced_definition(schema, completed, "item")
314
+ variants = _object_list(thread_item.get("oneOf"), "ThreadItem")
315
+ item_types = {_variant_tag(variant, "ThreadItem") for variant in variants}
316
+ if item_types != _KNOWN_THREAD_ITEMS:
317
+ raise CodexSchemaError("Codex app-server exposes unknown turn item types")
318
+ agent = next(
319
+ variant for variant in variants if _variant_tag(variant, "ThreadItem") == "agentMessage"
320
+ )
321
+ _require_properties(agent, {"id", "phase", "text", "type"}, "agentMessage")
322
+ message_phase = _referenced_definition(schema, agent, "phase")
323
+ if not _supports_string_enum_value(message_phase, "final_answer"):
324
+ raise CodexSchemaError("Codex app-server has no final-answer message phase")
325
+
326
+ usage_notification = _definition(schema, methods["thread/tokenUsage/updated"])
327
+ usage = _referenced_definition(schema, usage_notification, "tokenUsage")
328
+ _require_properties(usage, {"last", "total"}, "thread token usage")
329
+ usage_counts = _referenced_definition(schema, usage, "last")
330
+ _require_properties(
331
+ usage_counts,
332
+ {"cachedInputTokens", "inputTokens", "outputTokens"},
333
+ "token usage breakdown",
334
+ )
335
+ turn = _referenced_definition(schema, _definition(schema, methods["turn/completed"]), "turn")
336
+ _require_properties(turn, {"id", "items", "status"}, "completed turn")
337
+ thread = _referenced_definition(
338
+ schema, _definition(schema, methods["thread/started"]), "thread"
339
+ )
340
+ _require_properties(thread, {"id"}, "started thread")
341
+
342
+
343
+ def _verify_response_contract(documents: dict[str, dict[str, object]]) -> None:
344
+ _require_properties(
345
+ documents["v2/ThreadStartResponse.json"],
346
+ {"model", "serviceTier", "thread"},
347
+ "thread/start",
348
+ )
349
+ thread_start = documents["v2/ThreadStartResponse.json"]
350
+ _require_properties(
351
+ _referenced_definition(thread_start, thread_start, "thread"),
352
+ {"id", "model"},
353
+ "thread/start thread",
354
+ )
355
+ _require_properties(documents["v2/TurnStartResponse.json"], {"turn"}, "turn/start")
356
+ turn_start = documents["v2/TurnStartResponse.json"]
357
+ _require_properties(
358
+ _referenced_definition(turn_start, turn_start, "turn"),
359
+ {"id"},
360
+ "turn/start turn",
361
+ )
362
+ if not _property_supports_string_value(
363
+ documents["CommandExecutionRequestApprovalResponse.json"], "decision", "decline"
364
+ ):
365
+ raise CodexSchemaError("Codex command execution cannot be declined")
366
+ if not _property_supports_string_value(
367
+ documents["FileChangeRequestApprovalResponse.json"], "decision", "decline"
368
+ ):
369
+ raise CodexSchemaError("Codex file changes cannot be declined")
370
+ _require_properties(
371
+ documents["DynamicToolCallResponse.json"],
372
+ {"contentItems", "success"},
373
+ "dynamic tool response",
374
+ )
375
+ elicitation = documents["McpServerElicitationRequestResponse.json"]
376
+ _require_properties(elicitation, {"_meta", "action", "content"}, "MCP elicitation response")
377
+ if not _property_supports_string_value(elicitation, "action", "decline"):
378
+ raise CodexSchemaError("Codex MCP elicitation cannot be declined")
379
+
380
+
381
+ def _require_methods(schema: dict[str, object], expected: frozenset[str]) -> dict[str, str]:
382
+ methods = _method_definitions(schema)
383
+ if any(not methods.get(method) for method in expected):
384
+ raise CodexSchemaError("Codex app-server is missing a required protocol method")
385
+ return {method: methods[method] for method in expected}
386
+
387
+
388
+ def _method_definitions(schema: dict[str, object]) -> dict[str, str]:
389
+ variants = _object_list(schema.get("oneOf"), "request union")
390
+ methods: dict[str, str] = {}
391
+ for variant in variants:
392
+ properties = _object(variant.get("properties"), "request properties")
393
+ method_schema = _object(properties.get("method"), "request method")
394
+ values = method_schema.get("enum")
395
+ params = _object(properties.get("params"), "request parameters")
396
+ reference = params.get("$ref")
397
+ if not isinstance(values, list) or len(values) != 1 or not isinstance(values[0], str):
398
+ raise CodexSchemaError("Codex app-server request union has an invalid variant")
399
+ methods[values[0]] = (
400
+ reference.removeprefix("#/definitions/")
401
+ if isinstance(reference, str) and reference.startswith("#/definitions/")
402
+ else ""
403
+ )
404
+ return methods
405
+
406
+
407
+ def _variant_tag(variant: dict[str, object], label: str) -> str:
408
+ properties = _object(variant.get("properties"), label)
409
+ type_schema = _object(properties.get("type"), label)
410
+ values = type_schema.get("enum")
411
+ if not isinstance(values, list) or len(values) != 1 or not isinstance(values[0], str):
412
+ raise CodexSchemaError(f"Codex app-server {label} has an invalid variant")
413
+ return values[0]
414
+
415
+
416
+ def _definition(schema: dict[str, object], name: str) -> dict[str, object]:
417
+ definitions = _object(schema.get("definitions"), "schema definitions")
418
+ return _object(definitions.get(name), name)
419
+
420
+
421
+ def _require_properties(schema: dict[str, object], required: set[str], label: str) -> None:
422
+ properties = _object(schema.get("properties"), label)
423
+ if not required <= set(properties):
424
+ raise CodexSchemaError(f"Codex app-server {label} shape is unsupported")
425
+
426
+
427
+ def _property_supports_string_value(
428
+ schema: dict[str, object],
429
+ property_name: str,
430
+ value: str,
431
+ ) -> bool:
432
+ try:
433
+ return _supports_string_enum_value(
434
+ _referenced_definition(schema, schema, property_name), value
435
+ )
436
+ except CodexSchemaError:
437
+ return False
438
+
439
+
440
+ def _property(schema: dict[str, object], name: str) -> dict[str, object]:
441
+ properties = _object(schema.get("properties"), name)
442
+ return _object(properties.get(name), name)
443
+
444
+
445
+ def _referenced_definition(
446
+ schema: dict[str, object],
447
+ owner: dict[str, object],
448
+ property_name: str,
449
+ ) -> dict[str, object]:
450
+ property_schema = _property(owner, property_name)
451
+ references = [property_schema.get("$ref")]
452
+ variants = property_schema.get("anyOf")
453
+ if isinstance(variants, list):
454
+ references.extend(variant.get("$ref") for variant in variants if isinstance(variant, dict))
455
+ prefix = "#/definitions/"
456
+ names = {
457
+ reference.removeprefix(prefix)
458
+ for reference in references
459
+ if isinstance(reference, str) and reference.startswith(prefix)
460
+ }
461
+ if len(names) != 1:
462
+ raise CodexSchemaError(f"Codex app-server {property_name} reference is unsupported")
463
+ return _definition(schema, names.pop())
464
+
465
+
466
+ def _require_nullable_reference(
467
+ schema: dict[str, object],
468
+ property_name: str,
469
+ definition: str,
470
+ ) -> None:
471
+ variants = _object_list(_property(schema, property_name).get("anyOf"), property_name)
472
+ reference = f"#/definitions/{definition}"
473
+ if not any(variant.get("$ref") == reference for variant in variants) or not any(
474
+ variant.get("type") == "null" for variant in variants
475
+ ):
476
+ raise CodexSchemaError(f"Codex app-server {property_name} policy shape is unsupported")
477
+
478
+
479
+ def _enum_values(schema: dict[str, object], label: str) -> set[str]:
480
+ values = schema.get("enum")
481
+ if (
482
+ not isinstance(values, list)
483
+ or not values
484
+ or not all(isinstance(value, str) for value in values)
485
+ ):
486
+ raise CodexSchemaError(f"Codex app-server {label} has an invalid enum")
487
+ return set(cast(list[str], values))
488
+
489
+
490
+ def _supports_string_enum_value(schema: dict[str, object], value: str) -> bool:
491
+ values = schema.get("enum")
492
+ if schema.get("type") == "string" and isinstance(values, list) and value in values:
493
+ return True
494
+ variants = schema.get("oneOf")
495
+ return isinstance(variants, list) and any(
496
+ isinstance(variant, dict)
497
+ and variant.get("type") == "string"
498
+ and isinstance(variant.get("enum"), list)
499
+ and value in variant["enum"]
500
+ for variant in variants
501
+ )
502
+
503
+
504
+ def _tagged_variant(
505
+ schema: dict[str, object],
506
+ tag: str,
507
+ ) -> dict[str, object] | None:
508
+ variants = _object_list(schema.get("oneOf"), "tagged union")
509
+ for variant in variants:
510
+ type_schema = _property(variant, "type")
511
+ if type_schema.get("type") == "string" and tag in _enum_values(
512
+ type_schema, "tagged union type"
513
+ ):
514
+ return variant
515
+ return None
516
+
517
+
518
+ def _object(value: object, label: str) -> dict[str, object]:
519
+ if not isinstance(value, dict):
520
+ raise CodexSchemaError(f"Codex app-server {label} is invalid")
521
+ return cast(dict[str, object], value)
522
+
523
+
524
+ def _object_list(value: object, label: str) -> list[dict[str, object]]:
525
+ if not isinstance(value, list) or not value:
526
+ raise CodexSchemaError(f"Codex app-server {label} is invalid")
527
+ return [_object(item, label) for item in value]
@@ -0,0 +1,130 @@
1
+ """Validate protected output from one Codex app-server worker."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import cast
7
+
8
+ from ithrl.execution import MAX_NATIVE_OUTPUT_BYTES
9
+ from ithrl.runner.codex.protocol import (
10
+ MAX_CLIENT_PROTOCOL_MESSAGES,
11
+ MAX_PROTOCOL_LINE_BYTES,
12
+ MAX_PROTOCOL_MESSAGES,
13
+ CodexProtocolError,
14
+ ProtocolOutcome,
15
+ ProtocolStatus,
16
+ ProtocolUsage,
17
+ ProviderAcceptance,
18
+ validate_protocol_json,
19
+ )
20
+
21
+
22
+ def parse_transcript(data: bytes) -> ProtocolOutcome:
23
+ """Read the single terminal summary from protected worker output."""
24
+
25
+ if len(data) > MAX_NATIVE_OUTPUT_BYTES:
26
+ raise CodexProtocolError("transcript-limit", "Codex transcript exceeds the byte limit")
27
+ summaries: list[object] = []
28
+ lines = data.splitlines()
29
+ max_records = MAX_PROTOCOL_MESSAGES + MAX_CLIENT_PROTOCOL_MESSAGES + 1
30
+ if not lines or len(lines) > max_records:
31
+ raise CodexProtocolError("transcript-format", "Codex transcript has an invalid shape")
32
+ for line in lines:
33
+ if len(line) > MAX_PROTOCOL_LINE_BYTES:
34
+ raise CodexProtocolError("transcript-limit", "Codex transcript exceeds the line limit")
35
+ try:
36
+ record = json.loads(line)
37
+ except (UnicodeDecodeError, json.JSONDecodeError):
38
+ raise CodexProtocolError(
39
+ "transcript-json", "Codex transcript contains invalid JSON"
40
+ ) from None
41
+ if not isinstance(record, dict) or record.get("kind") not in {
42
+ "client",
43
+ "server",
44
+ "summary",
45
+ }:
46
+ raise CodexProtocolError("transcript-format", "Codex transcript has an invalid record")
47
+ validate_protocol_json(record)
48
+ if record["kind"] == "summary":
49
+ summaries.append(record.get("value"))
50
+ if len(summaries) != 1 or not isinstance(summaries[0], dict):
51
+ raise CodexProtocolError("transcript-summary", "Codex transcript has no unique summary")
52
+ try:
53
+ return _outcome_from_document(cast(dict[str, object], summaries[0]))
54
+ except (KeyError, TypeError, ValueError):
55
+ raise CodexProtocolError(
56
+ "transcript-summary", "Codex transcript summary is invalid"
57
+ ) from None
58
+
59
+
60
+ def _outcome_from_document(document: dict[str, object]) -> ProtocolOutcome:
61
+ expected = {
62
+ "status",
63
+ "error_code",
64
+ "final_text",
65
+ "model_returned",
66
+ "service_tier",
67
+ "usage",
68
+ "provider_acceptance",
69
+ "provider_calls_started",
70
+ "provider_calls_completed",
71
+ "actions_requested",
72
+ "actions_denied",
73
+ }
74
+ if set(document) not in (expected, expected | {"behavior_output_observed"}):
75
+ raise ValueError("unexpected summary fields")
76
+ output_observed = document.get("behavior_output_observed", True)
77
+ if type(output_observed) is not bool:
78
+ raise ValueError("output visibility must be a boolean")
79
+ status = document["status"]
80
+ acceptance = document["provider_acceptance"]
81
+ if status not in {"completed", "error"} or acceptance not in {
82
+ "not-started",
83
+ "accepted",
84
+ "unknown",
85
+ }:
86
+ raise ValueError("invalid outcome enum")
87
+ return ProtocolOutcome(
88
+ status=cast(ProtocolStatus, status),
89
+ error_code=_nullable_string(document["error_code"]),
90
+ final_text=_nullable_string(document["final_text"]),
91
+ model_returned=_nullable_string(document["model_returned"]),
92
+ service_tier=_nullable_string(document["service_tier"]),
93
+ usage=_usage(document["usage"]),
94
+ provider_acceptance=cast(ProviderAcceptance, acceptance),
95
+ provider_calls_started=_count(document["provider_calls_started"]),
96
+ provider_calls_completed=_count(document["provider_calls_completed"]),
97
+ actions_requested=_count(document["actions_requested"]),
98
+ actions_denied=_count(document["actions_denied"]),
99
+ behavior_output_observed=output_observed,
100
+ )
101
+
102
+
103
+ def _usage(value: object) -> ProtocolUsage | None:
104
+ if value is None:
105
+ return None
106
+ if not isinstance(value, dict) or set(value) != {
107
+ "input_tokens",
108
+ "output_tokens",
109
+ "cached_input_tokens",
110
+ }:
111
+ raise ValueError("invalid usage")
112
+ return ProtocolUsage(
113
+ input_tokens=_count(value["input_tokens"]),
114
+ output_tokens=_count(value["output_tokens"]),
115
+ cached_input_tokens=_count(value["cached_input_tokens"]),
116
+ )
117
+
118
+
119
+ def _nullable_string(value: object) -> str | None:
120
+ if value is None:
121
+ return None
122
+ if not isinstance(value, str) or not value:
123
+ raise ValueError("invalid optional string")
124
+ return value
125
+
126
+
127
+ def _count(value: object) -> int:
128
+ if type(value) is not int or value < 0:
129
+ raise ValueError("invalid count")
130
+ return value