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,93 @@
1
+ """Bounded JSONL decoding for GitHub Copilot CLI events."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import cast
7
+
8
+ from ithrl.context import validate_json_limits
9
+ from ithrl.runner.copilot.protocol.contracts import (
10
+ MAX_EVENT_DEPTH,
11
+ MAX_EVENT_ITEMS,
12
+ MAX_OUTPUT_BYTES,
13
+ MAX_OUTPUT_EVENTS,
14
+ MAX_OUTPUT_LINE_BYTES,
15
+ SUPPORTED_EVENTS,
16
+ CopilotProtocolError,
17
+ )
18
+
19
+
20
+ def decode_events(output: bytes) -> list[dict[str, object]]:
21
+ """Decode one bounded native JSONL stream."""
22
+
23
+ if not output:
24
+ raise CopilotProtocolError("empty-output", "Copilot returned no JSONL output")
25
+ if len(output) > MAX_OUTPUT_BYTES:
26
+ raise CopilotProtocolError("output-limit", "Copilot output exceeded the byte limit")
27
+ lines = output.splitlines()
28
+ if len(lines) > MAX_OUTPUT_EVENTS:
29
+ raise CopilotProtocolError("event-limit", "Copilot output exceeded the event limit")
30
+ if not lines or any(not line.strip() for line in lines):
31
+ raise CopilotProtocolError("invalid-jsonl", "Copilot returned invalid JSONL output")
32
+ return [decode_line(line) for line in lines]
33
+
34
+
35
+ def decode_line(line: bytes) -> dict[str, object]:
36
+ """Decode and bound one native event line."""
37
+
38
+ if not line or len(line) > MAX_OUTPUT_LINE_BYTES:
39
+ raise CopilotProtocolError("line-limit", "A Copilot output line exceeded the byte limit")
40
+ try:
41
+ value = json.loads(
42
+ line,
43
+ object_pairs_hook=_object_without_duplicates,
44
+ parse_constant=_reject_json_constant,
45
+ )
46
+ except (RecursionError, UnicodeDecodeError, json.JSONDecodeError):
47
+ raise CopilotProtocolError("invalid-json", "Copilot returned invalid JSON") from None
48
+ if not isinstance(value, dict):
49
+ raise CopilotProtocolError("invalid-event", "Copilot returned an invalid event")
50
+ try:
51
+ validate_json_limits(value, max_depth=MAX_EVENT_DEPTH, max_items=MAX_EVENT_ITEMS)
52
+ except ValueError:
53
+ raise CopilotProtocolError(
54
+ "event-limit", "A Copilot event exceeded structural limits"
55
+ ) from None
56
+ event = cast(dict[str, object], value)
57
+ event_type = event.get("type")
58
+ if not isinstance(event_type, str) or event_type not in SUPPORTED_EVENTS:
59
+ raise CopilotProtocolError(
60
+ "unsupported-event", "Copilot returned an unsupported event type"
61
+ )
62
+ if event.get("agentId") is not None:
63
+ raise CopilotProtocolError(
64
+ "subagent-event", "Copilot returned a subagent event in the selected turn"
65
+ )
66
+ return event
67
+
68
+
69
+ def event_data(event: dict[str, object]) -> dict[str, object]:
70
+ """Return the object payload from one decoded event."""
71
+
72
+ data = event.get("data")
73
+ if not isinstance(data, dict):
74
+ raise CopilotProtocolError("invalid-event", "Copilot returned an invalid event payload")
75
+ return cast(dict[str, object], data)
76
+
77
+
78
+ def _reject_json_constant(_value: str) -> None:
79
+ raise CopilotProtocolError("invalid-number", "Copilot returned a non-finite JSON number")
80
+
81
+
82
+ def _object_without_duplicates(pairs: list[tuple[str, object]]) -> dict[str, object]:
83
+ value: dict[str, object] = {}
84
+ for key, item in pairs:
85
+ if key in value:
86
+ raise CopilotProtocolError(
87
+ "duplicate-field", "Copilot returned a JSON object with duplicate fields"
88
+ )
89
+ value[key] = item
90
+ return value
91
+
92
+
93
+ __all__ = ["decode_events", "decode_line", "event_data"]
@@ -0,0 +1,418 @@
1
+ """Validate one GitHub Copilot CLI event sequence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from typing import cast
7
+
8
+ from ithrl.behavior import MAX_BEHAVIOR_TEXT_LENGTH
9
+ from ithrl.context import JsonObject
10
+ from ithrl.runner.contracts import ToolCall
11
+ from ithrl.runner.copilot.protocol.contracts import (
12
+ MAX_ID_LENGTH,
13
+ MAX_MODEL_LENGTH,
14
+ MAX_OUTPUT_LINE_BYTES,
15
+ STARTUP_EVENTS,
16
+ CopilotProtocolError,
17
+ CopilotProtocolOutcome,
18
+ ExpectedOutcome,
19
+ )
20
+ from ithrl.runner.copilot.protocol.decoding import decode_events, decode_line, event_data
21
+ from ithrl.runner.copilot.protocol.state import (
22
+ ProtocolState,
23
+ bind_model,
24
+ bind_turn,
25
+ bounded_string,
26
+ invalid_sequence,
27
+ match_tool_identity,
28
+ parse_usage,
29
+ require_matching_turn,
30
+ required_string,
31
+ )
32
+
33
+
34
+ def parse_output(output: bytes, *, expected: ExpectedOutcome) -> CopilotProtocolOutcome:
35
+ """Parse one bounded ``--output-format json`` stream and prove its outcome."""
36
+
37
+ events = decode_events(output)
38
+ state = ProtocolState(expected=expected)
39
+ for index, event in enumerate(events):
40
+ event_type = cast(str, event["type"])
41
+ if state.denial_seen:
42
+ _handle_post_denial_event(state, event_type, event_data(event))
43
+ continue
44
+ _handle_event(state, event_type, event)
45
+ if event_type == "result" and index != len(events) - 1:
46
+ raise CopilotProtocolError(
47
+ "continued-after-result",
48
+ "Copilot emitted events after its result",
49
+ )
50
+ return _finish(state)
51
+
52
+
53
+ def _handle_post_denial_event(
54
+ state: ProtocolState, event_type: str, data: dict[str, object]
55
+ ) -> None:
56
+ # Bounded draining can retain lifecycle records emitted during group shutdown.
57
+ # They do not invalidate the observed denial or prove another provider call.
58
+ if event_type == "assistant.turn_end" and not state.turn_ended:
59
+ require_matching_turn(state, data)
60
+ state.turn_ended = True
61
+ return
62
+ if event_type == "assistant.turn_start" and state.turn_ended and not state.continuation_started:
63
+ required_string(data, "turnId", max_length=MAX_ID_LENGTH)
64
+ state.continuation_started = True
65
+ return
66
+ if event_type == "session.background_tasks_changed" and not data:
67
+ return
68
+ if event_type == "model.call_final_result" and not state.turn_ended:
69
+ _handle_call_final_result(state, data)
70
+ return
71
+ if event_type == "session.usage_checkpoint" and state.turn_ended:
72
+ return
73
+ raise CopilotProtocolError(
74
+ "continued-after-denial",
75
+ "Copilot continued after the denied action",
76
+ )
77
+
78
+
79
+ def is_denied_tool_completion(line: bytes) -> bool:
80
+ """Return whether one bounded line is an explicit denied tool completion."""
81
+
82
+ try:
83
+ event = decode_line(line)
84
+ if event.get("type") != "tool.execution_complete":
85
+ return False
86
+ data = event_data(event)
87
+ error = data.get("error")
88
+ return (
89
+ data.get("success") is False
90
+ and isinstance(error, dict)
91
+ and error.get("code") == "denied"
92
+ )
93
+ except CopilotProtocolError:
94
+ return False
95
+
96
+
97
+ def _handle_event(state: ProtocolState, event_type: str, event: dict[str, object]) -> None:
98
+ if event_type in STARTUP_EVENTS:
99
+ _handle_startup_event(state, event)
100
+ return
101
+ if event_type == "result":
102
+ _handle_result(state, event)
103
+ return
104
+ _EVENT_HANDLERS[event_type](state, event_data(event))
105
+
106
+
107
+ def _handle_startup_event(state: ProtocolState, event: dict[str, object]) -> None:
108
+ if state.user_seen or state.turn_started or state.call_started:
109
+ invalid_sequence()
110
+ event_data(event)
111
+
112
+
113
+ def _handle_user_message(state: ProtocolState, data: dict[str, object]) -> None:
114
+ if state.user_seen or state.turn_started or state.call_started:
115
+ invalid_sequence()
116
+ bind_turn(state, required_string(data, "turnId", max_length=MAX_ID_LENGTH))
117
+ required_string(
118
+ data,
119
+ "content",
120
+ max_length=MAX_BEHAVIOR_TEXT_LENGTH,
121
+ allow_empty=True,
122
+ )
123
+ state.user_seen = True
124
+
125
+
126
+ def _handle_call_start(state: ProtocolState, data: dict[str, object]) -> None:
127
+ if not state.turn_started or state.call_started or state.message_seen or state.turn_ended:
128
+ invalid_sequence()
129
+ turn_id = required_string(data, "turnId", max_length=MAX_ID_LENGTH)
130
+ model = required_string(data, "model", max_length=MAX_MODEL_LENGTH)
131
+ bind_turn(state, turn_id)
132
+ bind_model(state, model)
133
+ state.call_started = True
134
+
135
+
136
+ def _handle_call_finished(state: ProtocolState, data: dict[str, object]) -> None:
137
+ if not state.call_started or state.call_finished or state.message_seen:
138
+ invalid_sequence()
139
+ require_matching_turn(state, data)
140
+ if data.get("outcome") != "success":
141
+ raise CopilotProtocolError("provider-failure", "Copilot reported a failed provider call")
142
+ if (model := data.get("model")) is not None:
143
+ bind_model(state, bounded_string(model, max_length=MAX_MODEL_LENGTH))
144
+ if "usage" in data:
145
+ reported_usage = parse_usage(data["usage"])
146
+ if state.usage is not None and reported_usage is not None and reported_usage != state.usage:
147
+ raise CopilotProtocolError(
148
+ "usage-mismatch", "Copilot output contains inconsistent token usage"
149
+ )
150
+ state.usage = reported_usage or state.usage
151
+ state.call_finished = True
152
+
153
+
154
+ def _handle_turn_start(state: ProtocolState, data: dict[str, object]) -> None:
155
+ if not state.user_seen or state.turn_started or state.message_seen or state.turn_ended:
156
+ invalid_sequence()
157
+ bind_turn(state, required_string(data, "turnId", max_length=MAX_ID_LENGTH))
158
+ state.turn_started = True
159
+
160
+
161
+ def _handle_usage(state: ProtocolState, data: dict[str, object]) -> None:
162
+ if not state.call_started or state.message_seen or state.usage is not None:
163
+ invalid_sequence()
164
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
165
+ state.usage = parse_usage(data)
166
+
167
+
168
+ def _handle_reasoning(state: ProtocolState, data: dict[str, object]) -> None:
169
+ if not state.call_started or not state.turn_started or state.turn_ended:
170
+ invalid_sequence()
171
+ required_string(data, "content", max_length=MAX_OUTPUT_LINE_BYTES, allow_empty=True)
172
+ required_string(data, "reasoningId", max_length=MAX_OUTPUT_LINE_BYTES)
173
+ if "model" in data:
174
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
175
+ if "turnId" in data:
176
+ require_matching_turn(state, data)
177
+ # Opaque timeline fields remain bounded by the decoder's encoded-line limit.
178
+ # Timeline content and rte metadata establish no outcome or accounting evidence.
179
+
180
+
181
+ def _handle_message(state: ProtocolState, data: dict[str, object]) -> None:
182
+ if not state.call_finished or state.message_seen or state.turn_ended:
183
+ invalid_sequence()
184
+ require_matching_turn(state, data)
185
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
186
+ required_string(data, "messageId", max_length=MAX_ID_LENGTH)
187
+ # Optional opaque provider metadata is not part of identity or completion proof.
188
+ if "apiCallId" in data:
189
+ required_string(data, "apiCallId", max_length=MAX_OUTPUT_LINE_BYTES, allow_empty=True)
190
+ requests = data.get("toolRequests")
191
+ if not isinstance(requests, list):
192
+ raise CopilotProtocolError("invalid-message", "Copilot returned an invalid message")
193
+ if state.expected == "final-response" or not requests:
194
+ _record_final_response(state, data, requests)
195
+ else:
196
+ _record_shell_request(state, data, requests)
197
+ state.message_seen = True
198
+
199
+
200
+ def _record_final_response(
201
+ state: ProtocolState,
202
+ data: dict[str, object],
203
+ requests: list[object],
204
+ ) -> None:
205
+ if requests:
206
+ raise CopilotProtocolError(
207
+ "unexpected-action", "Copilot requested an action instead of a final response"
208
+ )
209
+ state.final_text = required_string(
210
+ data,
211
+ "content",
212
+ max_length=MAX_BEHAVIOR_TEXT_LENGTH,
213
+ allow_empty=True,
214
+ )
215
+
216
+
217
+ def _record_shell_request(
218
+ state: ProtocolState,
219
+ data: dict[str, object],
220
+ requests: list[object],
221
+ ) -> None:
222
+ if data.get("content") != "" or len(requests) != 1:
223
+ raise CopilotProtocolError(
224
+ "ambiguous-action", "Copilot did not return exactly one shell action"
225
+ )
226
+ _record_tool_request(state, requests[0])
227
+
228
+
229
+ def _record_tool_request(state: ProtocolState, value: object) -> None:
230
+ if not isinstance(value, dict):
231
+ raise CopilotProtocolError("invalid-action", "Copilot returned an invalid action")
232
+ request = cast(dict[str, object], value)
233
+ tool_call_id = required_string(request, "toolCallId", max_length=MAX_ID_LENGTH)
234
+ name = required_string(request, "name", max_length=256)
235
+ if name not in {"bash", "shell"} or request.get("type", "function") != "function":
236
+ raise CopilotProtocolError("unsupported-action", "Copilot returned a non-shell action")
237
+ arguments = request.get("arguments")
238
+ if not isinstance(arguments, dict):
239
+ raise CopilotProtocolError("invalid-action", "Copilot returned invalid action arguments")
240
+ try:
241
+ tool_call = ToolCall(name=name, arguments=cast(JsonObject, arguments))
242
+ except (TypeError, ValueError):
243
+ raise CopilotProtocolError(
244
+ "invalid-action", "Copilot returned invalid action arguments"
245
+ ) from None
246
+ state.tool_call_id = tool_call_id
247
+ state.tool_call = tool_call
248
+
249
+
250
+ def _handle_tool_start(state: ProtocolState, data: dict[str, object]) -> None:
251
+ if (
252
+ state.expected != "shell-action"
253
+ or not state.message_seen
254
+ or state.tool_call is None
255
+ or state.tool_started
256
+ ):
257
+ invalid_sequence()
258
+ match_tool_identity(state, data)
259
+ require_matching_turn(state, data)
260
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
261
+ arguments = data.get("arguments")
262
+ if state.tool_call is None or arguments != state.tool_call.arguments:
263
+ raise CopilotProtocolError(
264
+ "action-mismatch", "Copilot action evidence does not match its request"
265
+ )
266
+ state.tool_started = True
267
+
268
+
269
+ def _handle_tool_complete(state: ProtocolState, data: dict[str, object]) -> None:
270
+ if state.expected != "shell-action" or not state.tool_started or state.denial_seen:
271
+ invalid_sequence()
272
+ match_tool_identity(state, data)
273
+ require_matching_turn(state, data)
274
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
275
+ error = data.get("error")
276
+ if (
277
+ data.get("success") is not False
278
+ or not isinstance(error, dict)
279
+ or error.get("code") != "denied"
280
+ or "result" in data
281
+ ):
282
+ raise CopilotProtocolError(
283
+ "action-not-denied", "Copilot did not prove that action execution was denied"
284
+ )
285
+ state.denial_seen = True
286
+
287
+
288
+ def _handle_background_tasks(state: ProtocolState, data: dict[str, object]) -> None:
289
+ if state.expected != "shell-action" or not state.tool_started or state.denial_seen or data:
290
+ invalid_sequence()
291
+
292
+
293
+ def _handle_turn_end(state: ProtocolState, data: dict[str, object]) -> None:
294
+ if (
295
+ state.final_text is None
296
+ or state.tool_call is not None
297
+ or not state.message_seen
298
+ or state.turn_ended
299
+ ):
300
+ invalid_sequence()
301
+ require_matching_turn(state, data)
302
+ state.turn_ended = True
303
+
304
+
305
+ def _handle_call_final_result(state: ProtocolState, data: dict[str, object]) -> None:
306
+ if not state.call_finished or state.turn_ended:
307
+ invalid_sequence()
308
+ bind_model(state, required_string(data, "model", max_length=MAX_MODEL_LENGTH))
309
+ if data.get("result") != "success" or data.get("isByok") is not False:
310
+ raise CopilotProtocolError(
311
+ "provider-failure", "Copilot did not report a successful managed provider call"
312
+ )
313
+
314
+
315
+ def _handle_usage_checkpoint(state: ProtocolState, _data: dict[str, object]) -> None:
316
+ if not state.turn_ended or state.idle_seen:
317
+ invalid_sequence()
318
+ # Session billing/cache telemetry is not per-call token or provider accounting.
319
+
320
+
321
+ def _handle_idle(state: ProtocolState, _data: dict[str, object]) -> None:
322
+ if (
323
+ state.final_text is None
324
+ or state.tool_call is not None
325
+ or not state.turn_ended
326
+ or state.idle_seen
327
+ ):
328
+ invalid_sequence()
329
+ state.idle_seen = True
330
+
331
+
332
+ def _handle_result(state: ProtocolState, event: dict[str, object]) -> None:
333
+ if (
334
+ state.final_text is None
335
+ or state.tool_call is not None
336
+ or not state.idle_seen
337
+ or state.result_seen
338
+ ):
339
+ invalid_sequence()
340
+ exit_code = event.get("exitCode")
341
+ if (
342
+ not isinstance(exit_code, int)
343
+ or isinstance(exit_code, bool)
344
+ or exit_code != 0
345
+ or not isinstance(event.get("usage"), dict)
346
+ ):
347
+ raise CopilotProtocolError("invalid-result", "Copilot returned an unsuccessful result")
348
+ required_string(event, "sessionId", max_length=MAX_ID_LENGTH)
349
+ state.result_seen = True
350
+
351
+
352
+ def _finish(state: ProtocolState) -> CopilotProtocolOutcome:
353
+ if not state.call_started or not state.call_finished or state.model is None:
354
+ raise CopilotProtocolError(
355
+ "missing-provider-evidence", "Copilot output lacks complete provider-call evidence"
356
+ )
357
+ if state.expected == "final-response" or state.final_text is not None:
358
+ return _finish_final_response(state, state.model)
359
+ return _finish_shell_action(state, state.model)
360
+
361
+
362
+ def _finish_final_response(state: ProtocolState, model: str) -> CopilotProtocolOutcome:
363
+ if not (
364
+ state.message_seen
365
+ and state.turn_ended
366
+ and state.idle_seen
367
+ and state.result_seen
368
+ and state.final_text is not None
369
+ ):
370
+ raise CopilotProtocolError(
371
+ "incomplete-final-response", "Copilot output lacks a complete final response"
372
+ )
373
+ return CopilotProtocolOutcome(
374
+ type="final-response",
375
+ model_returned=model,
376
+ provider_calls_started=1,
377
+ provider_calls_completed=1,
378
+ final_text=state.final_text,
379
+ usage=state.usage,
380
+ )
381
+
382
+
383
+ def _finish_shell_action(state: ProtocolState, model: str) -> CopilotProtocolOutcome:
384
+ if not state.denial_seen or state.tool_call is None:
385
+ raise CopilotProtocolError(
386
+ "incomplete-denial", "Copilot output lacks a complete denied shell action"
387
+ )
388
+ return CopilotProtocolOutcome(
389
+ type="shell-action",
390
+ model_returned=model,
391
+ provider_calls_started=1,
392
+ provider_calls_completed=1,
393
+ tool_call=state.tool_call,
394
+ usage=state.usage,
395
+ actions_requested=1,
396
+ actions_denied=1,
397
+ )
398
+
399
+
400
+ _EVENT_HANDLERS: dict[str, Callable[[ProtocolState, dict[str, object]], None]] = {
401
+ "user.message": _handle_user_message,
402
+ "model.call_start": _handle_call_start,
403
+ "model.call_finished": _handle_call_finished,
404
+ "model.call_final_result": _handle_call_final_result,
405
+ "assistant.turn_start": _handle_turn_start,
406
+ "assistant.usage": _handle_usage,
407
+ "assistant.message": _handle_message,
408
+ "assistant.reasoning": _handle_reasoning,
409
+ "tool.execution_start": _handle_tool_start,
410
+ "tool.execution_complete": _handle_tool_complete,
411
+ "session.background_tasks_changed": _handle_background_tasks,
412
+ "session.usage_checkpoint": _handle_usage_checkpoint,
413
+ "assistant.turn_end": _handle_turn_end,
414
+ "assistant.idle": _handle_idle,
415
+ }
416
+
417
+
418
+ __all__ = ["is_denied_tool_completion", "parse_output"]
@@ -0,0 +1,130 @@
1
+ """Mutable parse state and field invariants for Copilot events."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from typing import cast
7
+
8
+ from ithrl.runner.contracts import TokenUsage, ToolCall
9
+ from ithrl.runner.copilot.protocol.contracts import (
10
+ MAX_ID_LENGTH,
11
+ CopilotProtocolError,
12
+ ExpectedOutcome,
13
+ )
14
+
15
+
16
+ @dataclass(slots=True)
17
+ class ProtocolState:
18
+ """Evidence accumulated while validating one selected turn."""
19
+
20
+ expected: ExpectedOutcome
21
+ turn_id: str | None = None
22
+ model: str | None = None
23
+ user_seen: bool = False
24
+ call_started: bool = False
25
+ call_finished: bool = False
26
+ turn_started: bool = False
27
+ message_seen: bool = False
28
+ turn_ended: bool = False
29
+ idle_seen: bool = False
30
+ result_seen: bool = False
31
+ denial_seen: bool = False
32
+ continuation_started: bool = False
33
+ final_text: str | None = None
34
+ tool_call_id: str | None = None
35
+ tool_call: ToolCall | None = None
36
+ tool_started: bool = False
37
+ usage: TokenUsage | None = None
38
+
39
+
40
+ def parse_usage(value: object) -> TokenUsage | None:
41
+ """Parse token counts when Copilot reports them."""
42
+
43
+ if not isinstance(value, dict):
44
+ raise CopilotProtocolError("invalid-usage", "Copilot returned invalid token usage")
45
+ usage = cast(dict[str, object], value)
46
+ input_value = usage.get("inputTokens")
47
+ output_value = usage.get("outputTokens")
48
+ if input_value is None and output_value is None:
49
+ return None
50
+ if not _is_count(input_value) or not _is_count(output_value):
51
+ raise CopilotProtocolError("invalid-usage", "Copilot returned invalid token usage")
52
+ cached = usage.get("cacheReadTokens")
53
+ if cached is not None and not _is_count(cached):
54
+ raise CopilotProtocolError("invalid-usage", "Copilot returned invalid token usage")
55
+ return TokenUsage(
56
+ input_tokens=cast(int, input_value),
57
+ output_tokens=cast(int, output_value),
58
+ cached_input_tokens=cast(int | None, cached),
59
+ )
60
+
61
+
62
+ def required_string(
63
+ value: dict[str, object],
64
+ key: str,
65
+ *,
66
+ max_length: int,
67
+ allow_empty: bool = False,
68
+ ) -> str:
69
+ """Return one bounded string field."""
70
+
71
+ return bounded_string(value.get(key), max_length=max_length, allow_empty=allow_empty)
72
+
73
+
74
+ def bounded_string(value: object, *, max_length: int, allow_empty: bool = False) -> str:
75
+ """Validate one protocol string without exposing it in an error."""
76
+
77
+ if not isinstance(value, str) or len(value) > max_length or (not value and not allow_empty):
78
+ raise CopilotProtocolError("invalid-field", "Copilot returned an invalid event field")
79
+ return value
80
+
81
+
82
+ def bind_turn(state: ProtocolState, turn_id: str) -> None:
83
+ """Bind all selected-turn evidence to one identity."""
84
+
85
+ if state.turn_id is not None and state.turn_id != turn_id:
86
+ raise CopilotProtocolError(
87
+ "turn-mismatch", "Copilot output contains more than one selected turn"
88
+ )
89
+ state.turn_id = turn_id
90
+
91
+
92
+ def require_matching_turn(state: ProtocolState, data: dict[str, object]) -> None:
93
+ """Require an event to belong to the selected turn."""
94
+
95
+ bind_turn(state, required_string(data, "turnId", max_length=MAX_ID_LENGTH))
96
+
97
+
98
+ def bind_model(state: ProtocolState, model: str) -> None:
99
+ """Bind all provider evidence to one returned model identity."""
100
+
101
+ if state.model is not None and state.model != model:
102
+ raise CopilotProtocolError(
103
+ "model-mismatch", "Copilot output contains inconsistent model identities"
104
+ )
105
+ state.model = model
106
+
107
+
108
+ def match_tool_identity(state: ProtocolState, data: dict[str, object]) -> None:
109
+ """Require action lifecycle evidence to match the selected request."""
110
+
111
+ tool_call_id = required_string(data, "toolCallId", max_length=MAX_ID_LENGTH)
112
+ if tool_call_id != state.tool_call_id:
113
+ raise CopilotProtocolError(
114
+ "action-mismatch", "Copilot action evidence does not match its request"
115
+ )
116
+ tool_name = data.get("toolName")
117
+ if tool_name is not None and (state.tool_call is None or tool_name != state.tool_call.name):
118
+ raise CopilotProtocolError(
119
+ "action-mismatch", "Copilot action evidence does not match its request"
120
+ )
121
+
122
+
123
+ def invalid_sequence() -> None:
124
+ """Reject an event outside the supported lifecycle."""
125
+
126
+ raise CopilotProtocolError("invalid-sequence", "Copilot returned events in an invalid sequence")
127
+
128
+
129
+ def _is_count(value: object) -> bool:
130
+ return isinstance(value, int) and not isinstance(value, bool) and value >= 0