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,433 @@
1
+ """Composition root for built-in native session parsers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from collections.abc import Mapping, Sequence
7
+ from dataclasses import dataclass
8
+ from pathlib import Path
9
+ from typing import Protocol
10
+
11
+ from pydantic import ValidationError
12
+
13
+ from ithrl.adapters._jsonl import JsonlDocument, read_jsonl, read_jsonl_bytes
14
+ from ithrl.adapters.codex import PARSER as CODEX_PARSER
15
+ from ithrl.adapters.codex.context import compile_context as compile_codex_context
16
+ from ithrl.adapters.codex.decisions import enumerate_decisions as enumerate_codex_decisions
17
+ from ithrl.adapters.codex.discovery import discover_sources as discover_codex_sources
18
+ from ithrl.adapters.contracts import NativeSession, ParsingLimits
19
+ from ithrl.adapters.copilot import PARSER as COPILOT_PARSER
20
+ from ithrl.adapters.copilot.context import compile_context as compile_copilot_context
21
+ from ithrl.adapters.copilot.decisions import enumerate_decisions as enumerate_copilot_decisions
22
+ from ithrl.adapters.copilot.discovery import discover_sources as discover_copilot_sources
23
+ from ithrl.adapters.discovery import (
24
+ DiscoveredSession,
25
+ DiscoveryLimits,
26
+ DiscoveryResult,
27
+ HarnessName,
28
+ SessionSource,
29
+ SessionSummary,
30
+ SourceScan,
31
+ )
32
+ from ithrl.adapters.errors import AdapterError, AdapterErrorCode
33
+ from ithrl.context import ContextGraph
34
+ from ithrl.decisions import DecisionDraft, DecisionSelector, DecisionSummary, SelectedDecision
35
+
36
+
37
+ class NativeSessionParser(Protocol):
38
+ """One harness-specific detector and parser."""
39
+
40
+ format_name: str
41
+
42
+ def matches(self, document: JsonlDocument) -> bool: ...
43
+
44
+ def parse(self, document: JsonlDocument) -> NativeSession: ...
45
+
46
+
47
+ class DecisionEnumerator(Protocol):
48
+ """Interpret completed decisions in one validated native format."""
49
+
50
+ def __call__(self, session: NativeSession) -> tuple[DecisionDraft, ...]: ...
51
+
52
+
53
+ class ContextCompiler(Protocol):
54
+ """Compile context for one selected native decision."""
55
+
56
+ def __call__(self, session: NativeSession, selector: DecisionSelector) -> ContextGraph: ...
57
+
58
+
59
+ class SessionDiscoverer(Protocol):
60
+ """Find candidate files in one harness's ordinary local store."""
61
+
62
+ def __call__(
63
+ self,
64
+ *,
65
+ root: Path | None = None,
66
+ limits: DiscoveryLimits | None = None,
67
+ session_id: str | None = None,
68
+ ) -> SourceScan: ...
69
+
70
+
71
+ @dataclass(frozen=True, slots=True)
72
+ class _AdapterRegistration:
73
+ harness: HarnessName
74
+ parser: NativeSessionParser
75
+ discoverer: SessionDiscoverer
76
+ decision_enumerator: DecisionEnumerator
77
+ context_compiler: ContextCompiler
78
+
79
+
80
+ @dataclass(frozen=True, slots=True)
81
+ class _DiscoveryCollection:
82
+ sessions: tuple[DiscoveredSession, ...]
83
+ candidates_seen: int
84
+ rejected_candidates: int
85
+ rejection_codes: tuple[AdapterErrorCode, ...]
86
+
87
+
88
+ _BUILTIN_ADAPTERS = (
89
+ _AdapterRegistration(
90
+ harness="codex",
91
+ parser=CODEX_PARSER,
92
+ discoverer=discover_codex_sources,
93
+ decision_enumerator=enumerate_codex_decisions,
94
+ context_compiler=compile_codex_context,
95
+ ),
96
+ _AdapterRegistration(
97
+ harness="copilot",
98
+ parser=COPILOT_PARSER,
99
+ discoverer=discover_copilot_sources,
100
+ decision_enumerator=enumerate_copilot_decisions,
101
+ context_compiler=compile_copilot_context,
102
+ ),
103
+ )
104
+ _ADAPTERS_BY_HARNESS = {adapter.harness: adapter for adapter in _BUILTIN_ADAPTERS}
105
+ _ADAPTERS_BY_FORMAT = {adapter.parser.format_name: adapter for adapter in _BUILTIN_ADAPTERS}
106
+ _BUILTIN_PARSERS = tuple(adapter.parser for adapter in _BUILTIN_ADAPTERS)
107
+
108
+
109
+ def discover_sessions(
110
+ *,
111
+ harness: HarnessName | None = None,
112
+ roots: Mapping[HarnessName, Path] | None = None,
113
+ limits: DiscoveryLimits | None = None,
114
+ ) -> DiscoveryResult:
115
+ """Find recent supported sessions without exposing their captured content."""
116
+
117
+ selected_limits = limits or DiscoveryLimits()
118
+ scans = _discover_source_scans(harness, roots, selected_limits)
119
+ candidates = _ordered_sources(scans)
120
+ collection = _collect_sessions(candidates, selected_limits)
121
+ return DiscoveryResult(
122
+ sessions=collection.sessions,
123
+ candidates_seen=collection.candidates_seen,
124
+ rejected_candidates=collection.rejected_candidates,
125
+ rejection_codes=collection.rejection_codes,
126
+ truncated=(
127
+ any(scan.truncated for _, scan in scans) or collection.candidates_seen < len(candidates)
128
+ ),
129
+ )
130
+
131
+
132
+ def _discover_source_scans(
133
+ harness: HarnessName | None,
134
+ roots: Mapping[HarnessName, Path] | None,
135
+ limits: DiscoveryLimits,
136
+ ) -> tuple[tuple[HarnessName, SourceScan], ...]:
137
+ harnesses = (harness,) if harness is not None else tuple(_ADAPTERS_BY_HARNESS)
138
+ return tuple(
139
+ (
140
+ selected_harness,
141
+ _ADAPTERS_BY_HARNESS[selected_harness].discoverer(
142
+ root=roots.get(selected_harness) if roots is not None else None,
143
+ limits=limits,
144
+ ),
145
+ )
146
+ for selected_harness in harnesses
147
+ )
148
+
149
+
150
+ def _ordered_sources(
151
+ scans: tuple[tuple[HarnessName, SourceScan], ...],
152
+ ) -> tuple[tuple[SessionSource, HarnessName], ...]:
153
+ return tuple(
154
+ sorted(
155
+ ((candidate, harness) for harness, scan in scans for candidate in scan.sources),
156
+ key=_discovered_source_sort_key,
157
+ )
158
+ )
159
+
160
+
161
+ def _collect_sessions(
162
+ candidates: tuple[tuple[SessionSource, HarnessName], ...],
163
+ limits: DiscoveryLimits,
164
+ ) -> _DiscoveryCollection:
165
+ sessions: list[DiscoveredSession] = []
166
+ rejected = 0
167
+ rejection_codes: dict[AdapterErrorCode, None] = {}
168
+ considered = 0
169
+ parsed_bytes = 0
170
+ for source, expected_harness in candidates:
171
+ if len(sessions) == limits.max_sessions:
172
+ break
173
+ remaining_bytes = limits.max_parse_bytes - parsed_bytes
174
+ if remaining_bytes < 1:
175
+ break
176
+ considered += 1
177
+ session: NativeSession | None = None
178
+ try:
179
+ session = parse_session(
180
+ source.path,
181
+ limits=_parsing_limits(max_bytes=remaining_bytes),
182
+ )
183
+ parsed_bytes += session.source.size_bytes
184
+ summary = _summarize_session(session, expected_harness=expected_harness)
185
+ except AdapterError as error:
186
+ if session is None:
187
+ parsed_bytes += error.bytes_read
188
+ rejected += 1
189
+ rejection_codes.setdefault(error.code, None)
190
+ continue
191
+ sessions.append(
192
+ DiscoveredSession(
193
+ source=source,
194
+ summary=summary,
195
+ source_facts=session.source,
196
+ )
197
+ )
198
+ return _DiscoveryCollection(
199
+ sessions=tuple(sessions),
200
+ candidates_seen=considered,
201
+ rejected_candidates=rejected,
202
+ rejection_codes=tuple(rejection_codes),
203
+ )
204
+
205
+
206
+ def _discovered_source_sort_key(
207
+ item: tuple[SessionSource, HarnessName],
208
+ ) -> tuple[int, str]:
209
+ source, _ = item
210
+ return -source.modified_at_ns, source.path.as_posix()
211
+
212
+
213
+ def resolve_session(
214
+ *,
215
+ harness: HarnessName,
216
+ session_id: str,
217
+ root: Path | None = None,
218
+ limits: DiscoveryLimits | None = None,
219
+ ) -> NativeSession:
220
+ """Resolve one stable native session identifier within a known harness store."""
221
+
222
+ if not session_id or len(session_id) > 1024:
223
+ raise AdapterError(
224
+ AdapterErrorCode.SESSION_NOT_FOUND,
225
+ "session was not found in the selected harness store",
226
+ )
227
+ selected_limits = limits or DiscoveryLimits()
228
+ scan = _ADAPTERS_BY_HARNESS[harness].discoverer(
229
+ root=root,
230
+ limits=selected_limits,
231
+ session_id=session_id,
232
+ )
233
+ if not scan.sources:
234
+ raise AdapterError(
235
+ AdapterErrorCode.SESSION_NOT_FOUND,
236
+ "session was not found in the selected harness store",
237
+ )
238
+ if len(scan.sources) != 1 or scan.truncated:
239
+ raise AdapterError(
240
+ AdapterErrorCode.AMBIGUOUS_SESSION,
241
+ "session identifier matches more than one source file",
242
+ )
243
+ source = scan.sources[0]
244
+ if source.size_bytes > selected_limits.max_parse_bytes:
245
+ raise AdapterError(
246
+ AdapterErrorCode.DISCOVERY_LIMIT_EXCEEDED,
247
+ "session resolution exceeds the parse byte limit",
248
+ )
249
+ session = parse_session(
250
+ source.path,
251
+ limits=_parsing_limits(max_bytes=selected_limits.max_parse_bytes),
252
+ )
253
+ if session.metadata.format.harness != harness or session.metadata.session_id != session_id:
254
+ raise AdapterError(
255
+ AdapterErrorCode.INVALID_SESSION,
256
+ "session identifier does not match its native store entry",
257
+ )
258
+ return session
259
+
260
+
261
+ def _parsing_limits(*, max_bytes: int) -> ParsingLimits:
262
+ defaults = ParsingLimits()
263
+ candidate_max_bytes = min(defaults.max_bytes, max_bytes)
264
+ return ParsingLimits(
265
+ max_bytes=candidate_max_bytes,
266
+ max_line_bytes=min(defaults.max_line_bytes, candidate_max_bytes),
267
+ max_records=defaults.max_records,
268
+ max_json_items=defaults.max_json_items,
269
+ )
270
+
271
+
272
+ def reopen_discovered_session(discovered: DiscoveredSession) -> NativeSession:
273
+ """Reopen a listed session and refuse evidence changed after discovery."""
274
+
275
+ try:
276
+ session = parse_session(discovered.source.path)
277
+ except AdapterError:
278
+ raise AdapterError(
279
+ AdapterErrorCode.SOURCE_CHANGED,
280
+ "native session changed after it was listed",
281
+ ) from None
282
+ if session.source != discovered.source_facts or (
283
+ _summarize_session(session, expected_harness=discovered.summary.harness)
284
+ != discovered.summary
285
+ ):
286
+ raise AdapterError(
287
+ AdapterErrorCode.SOURCE_CHANGED,
288
+ "native session changed after it was listed",
289
+ )
290
+ return session
291
+
292
+
293
+ def parse_session(
294
+ path: str | os.PathLike[str],
295
+ *,
296
+ limits: ParsingLimits | None = None,
297
+ ) -> NativeSession:
298
+ """Detect and parse one supported native session JSONL file."""
299
+
300
+ document = read_jsonl(path, limits=limits or ParsingLimits())
301
+ try:
302
+ return _parse_document(document, _BUILTIN_PARSERS)
303
+ except AdapterError as error:
304
+ error.bytes_read = document.source.size_bytes
305
+ raise
306
+
307
+
308
+ def parse_session_bytes(
309
+ source: bytes,
310
+ *,
311
+ limits: ParsingLimits | None = None,
312
+ ) -> NativeSession:
313
+ """Detect and parse exact native session bytes retained by a case."""
314
+
315
+ document = read_jsonl_bytes(source, limits=limits or ParsingLimits())
316
+ return _parse_document(document, _BUILTIN_PARSERS)
317
+
318
+
319
+ def _parse_document(
320
+ document: JsonlDocument,
321
+ parsers: Sequence[NativeSessionParser],
322
+ ) -> NativeSession:
323
+ matches = tuple(parser for parser in parsers if parser.matches(document))
324
+ if not matches:
325
+ raise AdapterError(
326
+ AdapterErrorCode.UNSUPPORTED_FORMAT,
327
+ "session source does not match a supported native format",
328
+ )
329
+ if len(matches) > 1:
330
+ raise AdapterError(
331
+ AdapterErrorCode.AMBIGUOUS_FORMAT,
332
+ "session source matches more than one native format",
333
+ )
334
+ try:
335
+ return matches[0].parse(document)
336
+ except AdapterError:
337
+ raise
338
+ except (ValidationError, ValueError):
339
+ raise AdapterError(
340
+ AdapterErrorCode.INVALID_SESSION,
341
+ "session metadata is outside the supported bounds",
342
+ ) from None
343
+
344
+
345
+ def enumerate_decisions(session: NativeSession) -> tuple[DecisionSummary, ...]:
346
+ """List completed decisions without exposing their captured content."""
347
+
348
+ return tuple(draft.summarize() for draft in _decision_drafts(session))
349
+
350
+
351
+ def _summarize_session(
352
+ session: NativeSession,
353
+ *,
354
+ expected_harness: HarnessName,
355
+ ) -> SessionSummary:
356
+ if session.metadata.format.harness != expected_harness:
357
+ raise AdapterError(
358
+ AdapterErrorCode.UNSUPPORTED_FORMAT,
359
+ "session source does not match its native store layout",
360
+ )
361
+ decisions = enumerate_decisions(session)
362
+ if not decisions:
363
+ raise AdapterError(
364
+ AdapterErrorCode.INVALID_SESSION,
365
+ "session contains no supported completed decisions",
366
+ )
367
+ target_types = tuple(
368
+ dict.fromkeys(target.type for decision in decisions for target in decision.targets)
369
+ )
370
+ limitations = tuple(
371
+ dict.fromkeys(limitation for decision in decisions for limitation in decision.limitations)
372
+ )
373
+ return SessionSummary(
374
+ harness=expected_harness,
375
+ session_id=session.metadata.session_id,
376
+ producer_version=session.metadata.format.producer_version,
377
+ captured_at=session.metadata.captured_at,
378
+ decision_count=len(decisions),
379
+ target_types=target_types,
380
+ limitations=limitations,
381
+ )
382
+
383
+
384
+ def select_decision(
385
+ session: NativeSession,
386
+ *,
387
+ decision_id: str,
388
+ target_id: str,
389
+ ) -> SelectedDecision:
390
+ """Select one completed decision and behavior target by stable ID."""
391
+
392
+ drafts = _decision_drafts(session)
393
+ matches = tuple(draft for draft in drafts if draft.decision_id == decision_id)
394
+ if len(matches) != 1:
395
+ raise AdapterError(
396
+ AdapterErrorCode.DECISION_NOT_FOUND,
397
+ "completed decision was not found in the selected session",
398
+ )
399
+ draft = matches[0]
400
+ if target_id not in {candidate.target_id for candidate in draft.targets}:
401
+ raise AdapterError(
402
+ AdapterErrorCode.TARGET_NOT_FOUND,
403
+ "behavior target was not found for the selected decision",
404
+ )
405
+ compiler = _ADAPTERS_BY_FORMAT[session.metadata.format.name].context_compiler
406
+ try:
407
+ context = compiler(session, draft.selector)
408
+ except AdapterError:
409
+ raise
410
+ except (ValidationError, ValueError):
411
+ raise AdapterError(
412
+ AdapterErrorCode.INVALID_SESSION,
413
+ "session context cannot be compiled safely",
414
+ ) from None
415
+ return draft.select(target_id, context=context)
416
+
417
+
418
+ def _decision_drafts(session: NativeSession) -> tuple[DecisionDraft, ...]:
419
+ adapter = _ADAPTERS_BY_FORMAT.get(session.metadata.format.name)
420
+ if adapter is None:
421
+ raise AdapterError(
422
+ AdapterErrorCode.UNSUPPORTED_FORMAT,
423
+ "session format does not support decision enumeration",
424
+ )
425
+ try:
426
+ return adapter.decision_enumerator(session)
427
+ except AdapterError:
428
+ raise
429
+ except (ValidationError, ValueError):
430
+ raise AdapterError(
431
+ AdapterErrorCode.INVALID_SESSION,
432
+ "session decision metadata is not supported",
433
+ ) from None
ithrl/behavior.py ADDED
@@ -0,0 +1,138 @@
1
+ """Versioned deterministic behavior targets and observations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Annotated, Literal
6
+
7
+ from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, model_validator
8
+
9
+ from ithrl.context import content_digest
10
+
11
+ type BehaviorType = Literal["final-response", "shell-action"]
12
+
13
+ MAX_BEHAVIOR_TEXT_LENGTH = 64 * 1024
14
+ MAX_SHELL_ACTIONS = 32
15
+ MAX_TOOL_NAME_LENGTH = 256
16
+
17
+
18
+ class _ImmutableContract(BaseModel):
19
+ model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
20
+
21
+
22
+ class FinalResponseTarget(_ImmutableContract):
23
+ """Match a final response using at most one length-limited text condition."""
24
+
25
+ schema_version: Literal[1] = 1
26
+ type: Literal["final-response"] = "final-response"
27
+ text_equals: Annotated[str | None, Field(min_length=1, max_length=MAX_BEHAVIOR_TEXT_LENGTH)] = (
28
+ None
29
+ )
30
+ text_contains: Annotated[
31
+ str | None, Field(min_length=1, max_length=MAX_BEHAVIOR_TEXT_LENGTH)
32
+ ] = None
33
+
34
+ @model_validator(mode="after")
35
+ def validate_text_predicate(self) -> FinalResponseTarget:
36
+ if self.text_equals is not None and self.text_contains is not None:
37
+ raise ValueError("final-response target accepts only one text predicate")
38
+ return self
39
+
40
+ @property
41
+ def digest(self) -> str:
42
+ """Return the stable identity of the target contract."""
43
+
44
+ return target_digest(self)
45
+
46
+
47
+ class ShellActionTarget(_ImmutableContract):
48
+ """Match shell actions by tool identity and at most one command condition."""
49
+
50
+ schema_version: Literal[1] = 1
51
+ type: Literal["shell-action"] = "shell-action"
52
+ tool_name_equals: Annotated[
53
+ str | None, Field(min_length=1, max_length=MAX_TOOL_NAME_LENGTH)
54
+ ] = None
55
+ command_equals: Annotated[
56
+ str | None, Field(min_length=1, max_length=MAX_BEHAVIOR_TEXT_LENGTH)
57
+ ] = None
58
+ command_contains: Annotated[
59
+ str | None, Field(min_length=1, max_length=MAX_BEHAVIOR_TEXT_LENGTH)
60
+ ] = None
61
+ count: Annotated[int | None, Field(ge=1)] = None
62
+
63
+ @model_validator(mode="after")
64
+ def validate_command_predicate(self) -> ShellActionTarget:
65
+ if self.command_equals is not None and self.command_contains is not None:
66
+ raise ValueError("shell-action target accepts only one command predicate")
67
+ return self
68
+
69
+ @property
70
+ def digest(self) -> str:
71
+ """Return the stable identity of the target contract."""
72
+
73
+ return target_digest(self)
74
+
75
+
76
+ type BehaviorTarget = Annotated[
77
+ FinalResponseTarget | ShellActionTarget,
78
+ Field(discriminator="type"),
79
+ ]
80
+
81
+ _TARGET_ADAPTER = TypeAdapter(BehaviorTarget, config=ConfigDict(strict=True))
82
+
83
+
84
+ class ShellAction(_ImmutableContract):
85
+ """One normalized shell action retained alongside its native evidence."""
86
+
87
+ schema_version: Literal[1] = 1
88
+ tool_name: Annotated[str, Field(min_length=1, max_length=MAX_TOOL_NAME_LENGTH)]
89
+ command: Annotated[str, Field(max_length=MAX_BEHAVIOR_TEXT_LENGTH)]
90
+
91
+
92
+ class BehaviorObservation(_ImmutableContract):
93
+ """The normalized fields used by the built-in v0.1 targets."""
94
+
95
+ schema_version: Literal[1] = 1
96
+ final_response: Annotated[str | None, Field(max_length=MAX_BEHAVIOR_TEXT_LENGTH)] = None
97
+ shell_actions: Annotated[tuple[ShellAction, ...], Field(max_length=MAX_SHELL_ACTIONS)] = ()
98
+
99
+
100
+ def parse_behavior_target(value: object) -> BehaviorTarget:
101
+ """Validate an untrusted target object against the discriminated contract."""
102
+
103
+ return _TARGET_ADAPTER.validate_python(value)
104
+
105
+
106
+ def target_digest(target: BehaviorTarget) -> str:
107
+ """Return a deterministic SHA-256 digest for a behavior target."""
108
+
109
+ return content_digest(target.model_dump(mode="json", exclude_none=True))
110
+
111
+
112
+ def evaluate_target(target: BehaviorTarget, observation: BehaviorObservation) -> bool:
113
+ """Evaluate a target without model inference, regular expressions, or user code."""
114
+
115
+ if isinstance(target, FinalResponseTarget):
116
+ text = observation.final_response
117
+ if text is None:
118
+ return False
119
+ if target.text_equals is not None:
120
+ return text == target.text_equals
121
+ if target.text_contains is not None:
122
+ return target.text_contains in text
123
+ return True
124
+
125
+ matches = tuple(
126
+ action for action in observation.shell_actions if _matches_shell_action(target, action)
127
+ )
128
+ if target.count is not None:
129
+ return len(matches) == target.count
130
+ return bool(matches)
131
+
132
+
133
+ def _matches_shell_action(target: ShellActionTarget, action: ShellAction) -> bool:
134
+ if target.tool_name_equals is not None and action.tool_name != target.tool_name_equals:
135
+ return False
136
+ if target.command_equals is not None and action.command != target.command_equals:
137
+ return False
138
+ return target.command_contains is None or target.command_contains in action.command