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,484 @@
1
+ """Reconstruct GitHub Copilot semantic sessions from preserved native evidence."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from dataclasses import dataclass, field
7
+ from enum import StrEnum
8
+ from typing import Never
9
+
10
+ from ithrl.adapters.contracts import NativeSession
11
+ from ithrl.adapters.registry import parse_session_bytes
12
+ from ithrl.case import CaseFormatError
13
+ from ithrl.context import ContextNode, JsonObject, JsonValue, content_digest
14
+ from ithrl.extraction import validate_extracted_case
15
+ from ithrl.runner.contracts import PreparedAttempt
16
+ from ithrl.runner.copilot.policy import CAPTURE_TYPE, MATERIALIZATION, SOURCE_SCHEMA
17
+
18
+ _SOURCE_PATH = "source/events.jsonl"
19
+ _MAX_SEMANTIC_SESSION_BYTES = 64 * 1024 * 1024
20
+
21
+ # These records describe harness lifecycle or duplicate model telemetry. They are
22
+ # not conversation items in Copilot's semantic session interchange format.
23
+ _OMITTED_RECORD_TYPES = frozenset(
24
+ {
25
+ "assistant.turn_end",
26
+ "assistant.turn_start",
27
+ "model.captured_assignment_context",
28
+ "model.message",
29
+ "model.messages_snapshot",
30
+ "model.model_call_started",
31
+ "model.model_call_success",
32
+ "model.response",
33
+ "model.turn_ended",
34
+ "model.turn_started",
35
+ "session.task_complete",
36
+ }
37
+ )
38
+
39
+
40
+ class CopilotMaterializationErrorCode(StrEnum):
41
+ """Stable failure categories for source-backed Copilot reconstruction."""
42
+
43
+ INCOMPATIBLE_CASE = "incompatible-case"
44
+ CHANGED_EVIDENCE = "changed-evidence"
45
+ UNSUPPORTED_CONTEXT = "unsupported-context"
46
+ MISSING_TRIGGER = "missing-trigger"
47
+ AMBIGUOUS_BOUNDARY = "ambiguous-boundary"
48
+
49
+
50
+ class CopilotMaterializationError(RuntimeError):
51
+ """A Copilot candidate cannot be reconstructed without changing its meaning."""
52
+
53
+ def __init__(self, code: CopilotMaterializationErrorCode, message: str) -> None:
54
+ super().__init__(message)
55
+ self.code = code
56
+
57
+
58
+ @dataclass(frozen=True, slots=True)
59
+ class CopilotMaterialization:
60
+ """Private Copilot CLI inputs derived from one verified candidate."""
61
+
62
+ semantic_session: bytes = field(repr=False)
63
+ trigger: str = field(repr=False)
64
+
65
+
66
+ @dataclass(slots=True)
67
+ class _ToolSequence:
68
+ turn_id: str
69
+ name: str
70
+ arguments: JsonObject = field(repr=False)
71
+ started: bool = False
72
+ completed: bool = False
73
+
74
+
75
+ @dataclass(slots=True)
76
+ class _SemanticBuilder:
77
+ records: list[JsonObject]
78
+ tools: dict[str, _ToolSequence] = field(default_factory=dict)
79
+ retained_user_turns: set[str] = field(default_factory=set)
80
+ open_turns: dict[str, int] = field(default_factory=dict)
81
+
82
+ def add(self, record: JsonObject) -> None:
83
+ record_type = _required_native_string(record.get("type"))
84
+ if record_type == "user.message":
85
+ self._add_user(record)
86
+ elif record_type == "assistant.turn_start":
87
+ self._start_turn(record)
88
+ elif record_type == "assistant.turn_end":
89
+ self._end_turn(record)
90
+ elif record_type == "assistant.message":
91
+ self._add_assistant(record)
92
+ elif record_type == "tool.execution_start":
93
+ self._start_tool(record)
94
+ elif record_type == "tool.execution_complete":
95
+ self._complete_tool(record)
96
+ elif record_type not in _OMITTED_RECORD_TYPES:
97
+ _unsupported("the retained Copilot context contains an unsupported record")
98
+
99
+ def finish(self) -> tuple[JsonObject, ...]:
100
+ if any(not tool.completed for tool in self.tools.values()):
101
+ _unsupported("the retained Copilot context contains incomplete tool work")
102
+ if self.open_turns:
103
+ _unsupported("the retained Copilot context contains an incomplete assistant turn")
104
+ return tuple(self.records)
105
+
106
+ def _add_user(self, record: JsonObject) -> None:
107
+ if any(not tool.completed for tool in self.tools.values()):
108
+ _unsupported("the retained Copilot context contains incomplete tool work")
109
+ data = _object(record.get("data"))
110
+ content = _historical_user_content(data)
111
+ turn_id = _required_data_string(data, "turnId", "user turn identity is missing")
112
+ self.records.append(_semantic_message(record, role="user", content=content))
113
+ self.retained_user_turns.add(turn_id)
114
+
115
+ def _start_turn(self, record: JsonObject) -> None:
116
+ turn_id = _record_turn_id(record)
117
+ self.open_turns[turn_id] = self.open_turns.get(turn_id, 0) + 1
118
+
119
+ def _end_turn(self, record: JsonObject) -> None:
120
+ turn_id = _record_turn_id(record)
121
+ depth = self.open_turns.get(turn_id, 0)
122
+ if depth < 1:
123
+ _unsupported("the retained Copilot context has an unmatched assistant turn")
124
+ if depth == 1:
125
+ del self.open_turns[turn_id]
126
+ else:
127
+ self.open_turns[turn_id] = depth - 1
128
+
129
+ def _add_assistant(self, record: JsonObject) -> None:
130
+ if any(not tool.completed for tool in self.tools.values()):
131
+ _unsupported("the retained Copilot context contains incomplete tool work")
132
+ data = _object(record.get("data"))
133
+ turn_id = _required_data_string(data, "turnId", "assistant turn identity is missing")
134
+ if turn_id not in self.retained_user_turns or not self.open_turns.get(turn_id, 0):
135
+ _unsupported(
136
+ "the retained Copilot context contains an assistant message without a user"
137
+ )
138
+ content = data.get("content")
139
+ if not isinstance(content, str):
140
+ _unsupported("a retained Copilot assistant message has unsupported content")
141
+ self.records.append(_semantic_message(record, role="assistant", content=content))
142
+ requests = data.get("toolRequests")
143
+ if requests is None:
144
+ return
145
+ if not isinstance(requests, list):
146
+ _unsupported("a retained Copilot assistant message has unsupported tool requests")
147
+ self._add_tool_requests(record, turn_id, requests)
148
+
149
+ def _add_tool_requests(
150
+ self,
151
+ record: JsonObject,
152
+ turn_id: str,
153
+ requests: list[JsonValue],
154
+ ) -> None:
155
+ for request in requests:
156
+ if not isinstance(request, dict):
157
+ _unsupported("a retained Copilot assistant message has unsupported tool requests")
158
+ self._add_tool_request(record, turn_id, request)
159
+
160
+ def _add_tool_request(
161
+ self,
162
+ record: JsonObject,
163
+ turn_id: str,
164
+ request: JsonObject,
165
+ ) -> None:
166
+ tool_call_id = _required_data_string(request, "toolCallId", "tool call identity is missing")
167
+ if tool_call_id in self.tools:
168
+ _unsupported("the retained Copilot context repeats a tool call identity")
169
+ name = _required_data_string(request, "name", "tool call name is missing")
170
+ arguments = request.get("arguments")
171
+ if not isinstance(arguments, dict):
172
+ _unsupported("a retained Copilot tool call has unsupported arguments")
173
+ self.records.append(
174
+ {
175
+ "type": "tool-call",
176
+ "id": tool_call_id,
177
+ "timestamp": _record_timestamp(record),
178
+ "name": name,
179
+ "arguments": arguments,
180
+ }
181
+ )
182
+ self.tools[tool_call_id] = _ToolSequence(
183
+ turn_id=turn_id,
184
+ name=name,
185
+ arguments=arguments,
186
+ )
187
+
188
+ def _start_tool(self, record: JsonObject) -> None:
189
+ data = _object(record.get("data"))
190
+ tool_call_id = _required_data_string(data, "toolCallId", "tool start identity is missing")
191
+ tool = self.tools.get(tool_call_id)
192
+ if tool is None or tool.started:
193
+ _unsupported("the retained Copilot context has an invalid tool start")
194
+ if _required_data_string(data, "turnId", "tool turn identity is missing") != tool.turn_id:
195
+ _unsupported("the retained Copilot tool sequence crosses assistant turns")
196
+ if (
197
+ _required_data_string(data, "toolName", "tool start name is missing") != tool.name
198
+ or data.get("arguments") != tool.arguments
199
+ ):
200
+ _unsupported("the retained Copilot tool start does not match its request")
201
+ tool.started = True
202
+
203
+ def _complete_tool(self, record: JsonObject) -> None:
204
+ data = _object(record.get("data"))
205
+ tool_call_id = _required_data_string(data, "toolCallId", "tool result identity is missing")
206
+ tool = self.tools.get(tool_call_id)
207
+ if tool is None or not tool.started or tool.completed:
208
+ _unsupported("the retained Copilot context has an invalid tool result")
209
+ if _required_data_string(data, "turnId", "tool turn identity is missing") != tool.turn_id:
210
+ _unsupported("the retained Copilot tool sequence crosses assistant turns")
211
+ success = data.get("success")
212
+ if success is not True:
213
+ _unsupported("a retained Copilot tool result uses an unsupported failure shape")
214
+ result = data.get("result")
215
+ if not isinstance(result, dict) or set(result) != {"content"}:
216
+ _unsupported("a retained Copilot tool result uses an unsupported content shape")
217
+ content = _required_content(result.get("content"), "tool result")
218
+ self.records.append(
219
+ {
220
+ "type": "tool-result",
221
+ "id": _record_id(record),
222
+ "timestamp": _record_timestamp(record),
223
+ "toolCallId": tool_call_id,
224
+ "success": True,
225
+ "content": content,
226
+ }
227
+ )
228
+ tool.completed = True
229
+
230
+
231
+ def materialize_copilot_attempt(attempt: PreparedAttempt) -> CopilotMaterialization:
232
+ """Re-derive one selected Copilot attempt as semantic session input."""
233
+
234
+ _validate_compatible_attempt(attempt)
235
+ _validate_preserved_evidence(attempt)
236
+ return _materialize_session(attempt, _source_session(attempt))
237
+
238
+
239
+ def _validate_compatible_attempt(attempt: PreparedAttempt) -> None:
240
+ evidence = attempt.evidence
241
+ manifest = evidence.manifest
242
+ decision = evidence.decision
243
+ if (
244
+ attempt.candidate.materialization != MATERIALIZATION
245
+ or manifest.harness != "copilot"
246
+ or manifest.source_schema != SOURCE_SCHEMA
247
+ or manifest.capture.request != CAPTURE_TYPE
248
+ or decision is None
249
+ or decision.selector.kind != "copilot-assistant-message"
250
+ or attempt.target.type not in {"final-response", "shell-action"}
251
+ ):
252
+ raise CopilotMaterializationError(
253
+ CopilotMaterializationErrorCode.INCOMPATIBLE_CASE,
254
+ "the case is not a supported Copilot decision",
255
+ )
256
+
257
+
258
+ def _validate_preserved_evidence(attempt: PreparedAttempt) -> None:
259
+ try:
260
+ validate_extracted_case(attempt.evidence)
261
+ except CaseFormatError as error:
262
+ raise CopilotMaterializationError(
263
+ CopilotMaterializationErrorCode.CHANGED_EVIDENCE,
264
+ "the preserved Copilot evidence no longer matches the case",
265
+ ) from error
266
+
267
+
268
+ def _source_session(attempt: PreparedAttempt) -> NativeSession:
269
+ evidence = attempt.evidence
270
+ decision = evidence.decision
271
+ if decision is None:
272
+ raise CopilotMaterializationError(
273
+ CopilotMaterializationErrorCode.INCOMPATIBLE_CASE,
274
+ "the case has no selected Copilot decision",
275
+ )
276
+ source = next(
277
+ (
278
+ artifact
279
+ for artifact in evidence.source_artifacts
280
+ if artifact.path == decision.selector.source == _SOURCE_PATH
281
+ ),
282
+ None,
283
+ )
284
+ if source is None:
285
+ raise CopilotMaterializationError(
286
+ CopilotMaterializationErrorCode.INCOMPATIBLE_CASE,
287
+ "the case has no supported Copilot source artifact",
288
+ )
289
+ return parse_session_bytes(source.content)
290
+
291
+
292
+ def _materialize_session(
293
+ attempt: PreparedAttempt,
294
+ session: NativeSession,
295
+ ) -> CopilotMaterialization:
296
+ evidence = attempt.evidence
297
+ decision = evidence.decision
298
+ if decision is None:
299
+ raise CopilotMaterializationError(
300
+ CopilotMaterializationErrorCode.INCOMPATIBLE_CASE,
301
+ "the case has no selected Copilot decision",
302
+ )
303
+ records = session.records
304
+ boundary = decision.selector.context_before_line
305
+ trigger_record, trigger = _decision_trigger(records, boundary, decision.selector.turn_id)
306
+
307
+ retained = frozenset(attempt.candidate.retained_context_ids)
308
+ selected = _selected_context(evidence.context.nodes, records, boundary, retained)
309
+ if evidence.context.nodes[-1].id not in retained or selected[-1][1] is not trigger_record:
310
+ raise CopilotMaterializationError(
311
+ CopilotMaterializationErrorCode.MISSING_TRIGGER,
312
+ "the candidate removes the user message that triggered the selected decision",
313
+ )
314
+
315
+ semantic_session = _semantic_history(selected)
316
+ return CopilotMaterialization(semantic_session=semantic_session, trigger=trigger)
317
+
318
+
319
+ def _decision_trigger(
320
+ records: tuple[JsonObject, ...],
321
+ boundary: int,
322
+ turn_id: str,
323
+ ) -> tuple[JsonObject, str]:
324
+ if boundary < 3 or boundary > len(records):
325
+ _ambiguous("the selected Copilot decision has an invalid context boundary")
326
+ turn_start = records[boundary - 1]
327
+ if (
328
+ turn_start.get("type") != "assistant.turn_start"
329
+ or _object(turn_start.get("data")).get("turnId") != turn_id
330
+ ):
331
+ _ambiguous("the selected Copilot decision has no matching assistant turn boundary")
332
+ trigger = records[boundary - 2]
333
+ if trigger.get("type") != "user.message":
334
+ raise CopilotMaterializationError(
335
+ CopilotMaterializationErrorCode.MISSING_TRIGGER,
336
+ "the selected Copilot decision is not directly triggered by a user message",
337
+ )
338
+ trigger_data = _object(trigger.get("data"))
339
+ if trigger_data.get("turnId") != turn_id:
340
+ _ambiguous("the selected Copilot trigger and assistant turn do not match")
341
+ return trigger, _required_trigger(trigger_data.get("content"))
342
+
343
+
344
+ def _semantic_history(selected: list[tuple[str, JsonObject]]) -> bytes:
345
+ _, session_start = selected[0]
346
+ if session_start.get("type") != "session.start":
347
+ _ambiguous("the Copilot context does not begin with its session record")
348
+ builder = _SemanticBuilder(records=[_semantic_header(session_start)])
349
+ for _, record in selected[1:-1]:
350
+ builder.add(record)
351
+ return _encode_semantic_session(builder.finish())
352
+
353
+
354
+ def _selected_context(
355
+ nodes: tuple[ContextNode, ...],
356
+ records: tuple[JsonObject, ...],
357
+ boundary: int,
358
+ retained: frozenset[str],
359
+ ) -> list[tuple[str, JsonObject]]:
360
+ if len(nodes) != boundary - 1:
361
+ _ambiguous("the Copilot context graph does not match the selected boundary")
362
+ selected: list[tuple[str, JsonObject]] = []
363
+ for line, node in enumerate(nodes, start=1):
364
+ record = records[line - 1]
365
+ _validate_context_node(node, record, line)
366
+ if node.id in retained:
367
+ selected.append((node.id, record))
368
+ if not selected:
369
+ _ambiguous("the Copilot candidate has no retained session context")
370
+ return selected
371
+
372
+
373
+ def _validate_context_node(node: ContextNode, record: JsonObject, line: int) -> None:
374
+ selector = node.selector
375
+ if (
376
+ selector is None
377
+ or selector.line != line
378
+ or selector.identity_key != "id"
379
+ or selector.identity_value != record.get("id")
380
+ or node.source != _SOURCE_PATH
381
+ or node.digest != content_digest(record)
382
+ ):
383
+ _ambiguous("the Copilot context graph does not match its source records")
384
+
385
+
386
+ def _semantic_header(record: JsonObject) -> JsonObject:
387
+ data = _object(record.get("data"))
388
+ return {
389
+ "type": "session",
390
+ "version": 1,
391
+ "externalId": _required_data_string(data, "sessionId", "session identity is missing"),
392
+ "createdAt": _required_data_string(data, "startTime", "session start time is missing"),
393
+ }
394
+
395
+
396
+ def _semantic_message(record: JsonObject, *, role: str, content: str) -> JsonObject:
397
+ return {
398
+ "type": "message",
399
+ "id": _record_id(record),
400
+ "timestamp": _record_timestamp(record),
401
+ "role": role,
402
+ "content": [{"type": "text", "text": content}],
403
+ }
404
+
405
+
406
+ def _encode_semantic_session(records: tuple[JsonObject, ...]) -> bytes:
407
+ encoded = b"".join(
408
+ json.dumps(record, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode(
409
+ "utf-8"
410
+ )
411
+ + b"\n"
412
+ for record in records
413
+ )
414
+ if len(encoded) > _MAX_SEMANTIC_SESSION_BYTES:
415
+ _unsupported("the reconstructed Copilot semantic session exceeds the byte limit")
416
+ return encoded
417
+
418
+
419
+ def _record_id(record: JsonObject) -> str:
420
+ return _required_native_string(record.get("id"))
421
+
422
+
423
+ def _record_timestamp(record: JsonObject) -> str:
424
+ return _required_native_string(record.get("timestamp"))
425
+
426
+
427
+ def _record_turn_id(record: JsonObject) -> str:
428
+ return _required_data_string(
429
+ _object(record.get("data")),
430
+ "turnId",
431
+ "assistant turn identity is missing",
432
+ )
433
+
434
+
435
+ def _required_data_string(document: JsonObject, field_name: str, message: str) -> str:
436
+ value = document.get(field_name)
437
+ if not isinstance(value, str) or not value:
438
+ _unsupported(message)
439
+ return value
440
+
441
+
442
+ def _required_native_string(value: JsonValue | None) -> str:
443
+ if not isinstance(value, str) or not value:
444
+ _ambiguous("a Copilot source record has an invalid identity")
445
+ return value
446
+
447
+
448
+ def _required_content(value: JsonValue | None, kind: str) -> str:
449
+ if not isinstance(value, str):
450
+ _unsupported(f"a retained Copilot {kind} has unsupported content")
451
+ return value
452
+
453
+
454
+ def _historical_user_content(data: JsonObject) -> str:
455
+ if "transformedContent" in data:
456
+ return _required_content(data.get("transformedContent"), "transformed user message")
457
+ return _required_content(data.get("content"), "message")
458
+
459
+
460
+ def _required_trigger(value: JsonValue | None) -> str:
461
+ if not isinstance(value, str) or not value:
462
+ raise CopilotMaterializationError(
463
+ CopilotMaterializationErrorCode.MISSING_TRIGGER,
464
+ "the selected Copilot decision has no supported user trigger",
465
+ )
466
+ return value
467
+
468
+
469
+ def _object(value: JsonValue | None) -> JsonObject:
470
+ return value if isinstance(value, dict) else {}
471
+
472
+
473
+ def _unsupported(message: str) -> Never:
474
+ raise CopilotMaterializationError(
475
+ CopilotMaterializationErrorCode.UNSUPPORTED_CONTEXT,
476
+ message,
477
+ )
478
+
479
+
480
+ def _ambiguous(message: str) -> Never:
481
+ raise CopilotMaterializationError(
482
+ CopilotMaterializationErrorCode.AMBIGUOUS_BOUNDARY,
483
+ message,
484
+ )
@@ -0,0 +1,110 @@
1
+ """Fixed safety policy for GitHub Copilot CLI runner targets."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from typing import Literal
7
+
8
+ type CopilotTarget = Literal["final-response", "shell-action"]
9
+
10
+ RUNNER_VERSION = "1"
11
+ CAPTURE_TYPE = "logical-session"
12
+ CONTEXT_OPERATION = "dependency-closed-removal"
13
+ MATERIALIZATION = "source-backed"
14
+ RECONSTRUCTION_METHOD = "copilot-semantic-session-import-v1"
15
+ SOURCE_SCHEMA = "copilot-events-jsonl"
16
+ PROTOCOL_VERSION = "copilot-jsonl-v1"
17
+ PROVIDER = "github-copilot"
18
+ ENDPOINT = "copilot://managed"
19
+ POLICY_VERSION = "copilot-controlled-session-v1"
20
+ DISCOVERY_POLICY_VERSION = "copilot-isolated-discovery-v1"
21
+
22
+ # Copilot treats --available-tools as an allowlist. A name which cannot identify a
23
+ # built-in or configured tool therefore gives the final-response profile an empty
24
+ # tool surface. Capability detection verifies the allowlist option before this
25
+ # profile is advertised.
26
+ NO_TOOLS_SENTINEL = "ithrl-no-tools"
27
+
28
+ _COMMON_FLAGS = (
29
+ "--no-auto-update",
30
+ "--no-custom-instructions",
31
+ "--disable-builtin-mcps",
32
+ "--no-remote",
33
+ "--no-remote-export",
34
+ "--no-experimental",
35
+ "--no-ask-user",
36
+ "--no-bash-env",
37
+ "--dynamic-retrieval=skills=off",
38
+ "--output-format=json",
39
+ "--stream=off",
40
+ "--log-level=none",
41
+ )
42
+
43
+
44
+ @dataclass(frozen=True, slots=True)
45
+ class CopilotTargetPolicy:
46
+ """Target-specific command flags and advertised action guarantees."""
47
+
48
+ target: CopilotTarget
49
+ command_flags: tuple[str, ...]
50
+ action_visibility: Literal["not-applicable", "visible"]
51
+ action_denial: Literal["enforced"]
52
+
53
+
54
+ def target_policy(target: CopilotTarget) -> CopilotTargetPolicy:
55
+ """Return the fixed policy for one supported Copilot behavior target."""
56
+
57
+ if target == "final-response":
58
+ return CopilotTargetPolicy(
59
+ target=target,
60
+ command_flags=(
61
+ *_COMMON_FLAGS,
62
+ f"--available-tools={NO_TOOLS_SENTINEL}",
63
+ "--allow-all-tools",
64
+ "--disallow-temp-dir",
65
+ ),
66
+ action_visibility="not-applicable",
67
+ action_denial="enforced",
68
+ )
69
+ if target == "shell-action":
70
+ return CopilotTargetPolicy(
71
+ target=target,
72
+ command_flags=(
73
+ *_COMMON_FLAGS,
74
+ "--available-tools=bash",
75
+ "--allow-all-tools",
76
+ "--deny-tool=shell",
77
+ "--disallow-temp-dir",
78
+ ),
79
+ action_visibility="visible",
80
+ action_denial="enforced",
81
+ )
82
+ raise ValueError("unsupported Copilot target")
83
+
84
+
85
+ def policy_deviation(target: CopilotTarget) -> str:
86
+ """Describe the controlled surface without claiming historical replay."""
87
+
88
+ if target == "final-response":
89
+ return "the model sees no Copilot tools through an explicit availability allowlist"
90
+ return "only Copilot's native bash tool is visible and its shell permission is denied"
91
+
92
+
93
+ __all__ = [
94
+ "CAPTURE_TYPE",
95
+ "CONTEXT_OPERATION",
96
+ "DISCOVERY_POLICY_VERSION",
97
+ "ENDPOINT",
98
+ "MATERIALIZATION",
99
+ "NO_TOOLS_SENTINEL",
100
+ "POLICY_VERSION",
101
+ "PROTOCOL_VERSION",
102
+ "PROVIDER",
103
+ "RECONSTRUCTION_METHOD",
104
+ "RUNNER_VERSION",
105
+ "SOURCE_SCHEMA",
106
+ "CopilotTarget",
107
+ "CopilotTargetPolicy",
108
+ "policy_deviation",
109
+ "target_policy",
110
+ ]
@@ -0,0 +1,18 @@
1
+ """Parse bounded GitHub Copilot CLI JSONL outcomes."""
2
+
3
+ from ithrl.runner.copilot.protocol.contracts import (
4
+ MAX_OUTPUT_LINE_BYTES,
5
+ CopilotProtocolError,
6
+ CopilotProtocolOutcome,
7
+ ExpectedOutcome,
8
+ )
9
+ from ithrl.runner.copilot.protocol.parser import is_denied_tool_completion, parse_output
10
+
11
+ __all__ = [
12
+ "MAX_OUTPUT_LINE_BYTES",
13
+ "CopilotProtocolError",
14
+ "CopilotProtocolOutcome",
15
+ "ExpectedOutcome",
16
+ "is_denied_tool_completion",
17
+ "parse_output",
18
+ ]
@@ -0,0 +1,74 @@
1
+ """Data contracts and limits for GitHub Copilot CLI JSONL output."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from typing import Literal
7
+
8
+ from ithrl.runner.contracts import TokenUsage, ToolCall
9
+
10
+ type ExpectedOutcome = Literal["final-response", "shell-action"]
11
+
12
+ MAX_OUTPUT_BYTES = 8 * 1024 * 1024
13
+ MAX_OUTPUT_EVENTS = 256
14
+ MAX_OUTPUT_LINE_BYTES = 1024 * 1024
15
+ MAX_EVENT_DEPTH = 32
16
+ MAX_EVENT_ITEMS = 8192
17
+ MAX_ID_LENGTH = 512
18
+ MAX_MODEL_LENGTH = 256
19
+
20
+ SUPPORTED_EVENTS = frozenset(
21
+ {
22
+ "assistant.idle",
23
+ "assistant.message",
24
+ "assistant.reasoning",
25
+ "assistant.turn_end",
26
+ "assistant.turn_start",
27
+ "assistant.usage",
28
+ "model.call_finished",
29
+ "model.call_final_result",
30
+ "model.call_start",
31
+ "result",
32
+ "session.background_tasks_changed",
33
+ "session.info",
34
+ "session.mcp_servers_loaded",
35
+ "session.skills_loaded",
36
+ "session.tools_updated",
37
+ "session.usage_checkpoint",
38
+ "tool.execution_complete",
39
+ "tool.execution_start",
40
+ "user.message",
41
+ }
42
+ )
43
+ STARTUP_EVENTS = frozenset(
44
+ {
45
+ "session.info",
46
+ "session.mcp_servers_loaded",
47
+ "session.skills_loaded",
48
+ "session.tools_updated",
49
+ }
50
+ )
51
+
52
+
53
+ class CopilotProtocolError(ValueError):
54
+ """A content-safe refusal to interpret Copilot CLI output."""
55
+
56
+ def __init__(self, code: str, message: str) -> None:
57
+ super().__init__(message)
58
+ self.code = code
59
+
60
+
61
+ @dataclass(frozen=True, slots=True)
62
+ class CopilotProtocolOutcome:
63
+ """Normalized facts proved by one complete Copilot CLI event stream."""
64
+
65
+ type: ExpectedOutcome
66
+ model_returned: str
67
+ provider_calls_started: int
68
+ provider_calls_completed: int
69
+ final_text: str | None = field(default=None, repr=False)
70
+ tool_call: ToolCall | None = field(default=None, repr=False)
71
+ usage: TokenUsage | None = None
72
+ actions_requested: int = 0
73
+ actions_denied: int = 0
74
+ actions_executed: int = 0