ithrl 0.1.0__py3-none-any.whl

ithrl/__init__.py

@@ -0,0 +1 @@
+"""Find agent context that preserves or changes a model decision."""

ithrl/__main__.py

@@ -0,0 +1,6 @@
+"""Run the ithrl command-line interface with ``python -m ithrl``."""
+
+from ithrl.cli import app
+
+if __name__ == "__main__":
+    app()

ithrl/adapters/__init__.py

@@ -0,0 +1,49 @@
+"""Read and validate native coding-agent session evidence."""
+
+from ithrl.adapters.contracts import (
+    NativeSession,
+    ParsingLimits,
+    SessionFormat,
+    SessionMetadata,
+    SourceFacts,
+)
+from ithrl.adapters.discovery import (
+    DiscoveredSession,
+    DiscoveryLimits,
+    DiscoveryResult,
+    HarnessName,
+    SessionSummary,
+)
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.adapters.registry import (
+    discover_sessions,
+    enumerate_decisions,
+    parse_session,
+    reopen_discovered_session,
+    resolve_session,
+    select_decision,
+)
+from ithrl.decisions import DecisionSummary, SelectedDecision
+
+__all__ = [
+    "AdapterError",
+    "AdapterErrorCode",
+    "DecisionSummary",
+    "DiscoveredSession",
+    "DiscoveryLimits",
+    "DiscoveryResult",
+    "HarnessName",
+    "NativeSession",
+    "ParsingLimits",
+    "SelectedDecision",
+    "SessionFormat",
+    "SessionMetadata",
+    "SessionSummary",
+    "SourceFacts",
+    "discover_sessions",
+    "enumerate_decisions",
+    "parse_session",
+    "reopen_discovered_session",
+    "resolve_session",
+    "select_decision",
+]

ithrl/adapters/_jsonl.py

@@ -0,0 +1,266 @@
+"""Bounded reader for untrusted native JSONL evidence."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ithrl.adapters.contracts import ParsingLimits, SourceFacts
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.context import JsonObject, validate_json_limits
+from ithrl.path_safety import UnsafePathError, validate_directory_chain
+
+
+@dataclass(frozen=True, slots=True)
+class JsonlDocument:
+    raw: bytes
+    records: tuple[JsonObject, ...]
+    source: SourceFacts
+
+
+type _SourceSignature = tuple[int, int, int, int, int]
+
+
+class _DuplicateKeyError(ValueError):
+    pass
+
+
+def read_jsonl(path: str | os.PathLike[str], *, limits: ParsingLimits) -> JsonlDocument:
+    """Read one regular JSONL file and reject links or concurrent source replacement."""
+
+    source_path = Path(path)
+    try:
+        validate_directory_chain(source_path.parent)
+    except UnsafePathError:
+        raise AdapterError(
+            AdapterErrorCode.UNSAFE_SOURCE,
+            "session source has an unsafe controlling directory",
+        ) from None
+    initial = _lstat(source_path)
+    if stat.S_ISLNK(initial.st_mode) or not stat.S_ISREG(initial.st_mode):
+        raise AdapterError(AdapterErrorCode.UNSAFE_SOURCE, "session source must be a regular file")
+    if initial.st_size > limits.max_bytes:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_TOO_LARGE, "session source exceeds the byte limit"
+        )
+
+    descriptor = _open_read_only(source_path)
+    try:
+        opened = os.fstat(descriptor)
+        if not stat.S_ISREG(opened.st_mode):
+            raise AdapterError(
+                AdapterErrorCode.SOURCE_CHANGED,
+                "session source changed while opening",
+            )
+        if _signature(initial) != _signature(opened):
+            raise AdapterError(
+                AdapterErrorCode.SOURCE_CHANGED, "session source changed while opening"
+            )
+        with os.fdopen(descriptor, "rb") as handle:
+            descriptor = -1
+            raw = handle.read(min(opened.st_size, limits.max_bytes) + 1)
+            finished = os.fstat(handle.fileno())
+    except OSError:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_UNAVAILABLE, "cannot read session source"
+        ) from None
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+    if len(raw) > limits.max_bytes:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_TOO_LARGE,
+            "session source exceeds the byte limit",
+            bytes_read=len(raw),
+        )
+    try:
+        current = _lstat(source_path, changed=True)
+    except AdapterError as error:
+        error.bytes_read = len(raw)
+        raise
+    if _signature(opened) != _signature(finished) or _signature(opened) != _signature(current):
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_CHANGED,
+            "session source changed while reading",
+            bytes_read=len(raw),
+        )
+
+    try:
+        return read_jsonl_bytes(raw, limits=limits)
+    except AdapterError as error:
+        error.bytes_read = len(raw)
+        raise
+
+
+def read_jsonl_bytes(raw: bytes, *, limits: ParsingLimits) -> JsonlDocument:
+    """Parse one in-memory JSONL snapshot under the native evidence limits."""
+
+    if len(raw) > limits.max_bytes:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_TOO_LARGE, "session source exceeds the byte limit"
+        )
+    records = _parse_lines(raw, limits)
+    return JsonlDocument(
+        raw=raw,
+        records=records,
+        source=SourceFacts(sha256=hashlib.sha256(raw).hexdigest(), size_bytes=len(raw)),
+    )
+
+
+def _lstat(path: Path, *, changed: bool = False) -> os.stat_result:
+    try:
+        return path.lstat()
+    except OSError:
+        if changed:
+            raise AdapterError(
+                AdapterErrorCode.SOURCE_CHANGED, "session source changed while reading"
+            ) from None
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_UNAVAILABLE, "session source is unavailable"
+        ) from None
+
+
+def _open_read_only(path: Path) -> int:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    try:
+        return os.open(path, flags)
+    except OSError:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_UNAVAILABLE, "cannot open session source"
+        ) from None
+
+
+def _signature(metadata: os.stat_result) -> _SourceSignature:
+    return (
+        metadata.st_dev,
+        metadata.st_ino,
+        metadata.st_size,
+        metadata.st_mtime_ns,
+        metadata.st_ctime_ns,
+    )
+
+
+def _parse_lines(raw: bytes, limits: ParsingLimits) -> tuple[JsonObject, ...]:
+    records: list[JsonObject] = []
+    json_items = 0
+    start = 0
+    while start < len(raw):
+        end = raw.find(b"\n", start)
+        next_start = len(raw) if end < 0 else end + 1
+        end = len(raw) if end < 0 else end
+        line_number = len(records) + 1
+        if line_number > limits.max_records:
+            raise AdapterError(
+                AdapterErrorCode.TOO_MANY_RECORDS, "session source exceeds the record limit"
+            )
+        if end - start > limits.max_line_bytes:
+            raise AdapterError(
+                AdapterErrorCode.LINE_TOO_LARGE,
+                "session record exceeds the line limit",
+                line=line_number,
+            )
+
+        line = raw[start:end].removesuffix(b"\r")
+        if not line:
+            raise AdapterError(
+                AdapterErrorCode.INVALID_JSONL,
+                "session source contains a blank record",
+                line=line_number,
+            )
+        record = _parse_record(line, line_number)
+        json_items += _count_json_items(record)
+        if json_items > limits.max_json_items:
+            raise AdapterError(
+                AdapterErrorCode.JSON_LIMIT_EXCEEDED,
+                "session source exceeds the JSON item limit",
+                line=line_number,
+            )
+        records.append(record)
+        start = next_start
+    if not records:
+        raise AdapterError(AdapterErrorCode.INVALID_JSONL, "session source contains no records")
+    return tuple(records)
+
+
+def _parse_record(raw: bytes, line_number: int) -> JsonObject:
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeError:
+        raise AdapterError(
+            AdapterErrorCode.INVALID_UTF8,
+            "session source is not valid UTF-8",
+            line=line_number,
+        ) from None
+
+    try:
+        value: Any = json.loads(
+            text,
+            object_pairs_hook=_reject_duplicate_keys,
+            parse_constant=_reject_constant,
+        )
+    except _DuplicateKeyError:
+        raise AdapterError(
+            AdapterErrorCode.DUPLICATE_KEY,
+            "session record contains a duplicate object key",
+            line=line_number,
+        ) from None
+    except (ValueError, RecursionError):
+        raise AdapterError(
+            AdapterErrorCode.INVALID_JSONL,
+            "session record is not valid JSON",
+            line=line_number,
+        ) from None
+    if not isinstance(value, dict):
+        raise AdapterError(
+            AdapterErrorCode.INVALID_JSONL,
+            "session record must be a JSON object",
+            line=line_number,
+        )
+    try:
+        validate_json_limits(value)
+    except ValueError:
+        raise AdapterError(
+            AdapterErrorCode.JSON_LIMIT_EXCEEDED,
+            "session record exceeds JSON structure limits",
+            line=line_number,
+        ) from None
+    return value
+
+
+def _count_json_items(value: JsonObject) -> int:
+    items = 0
+    pending: list[object] = [value]
+    while pending:
+        current = pending.pop()
+        if isinstance(current, dict):
+            items += len(current)
+            pending.extend(current.values())
+        elif isinstance(current, list):
+            items += len(current)
+            pending.extend(current)
+    return items
+
+
+def _reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    value: dict[str, object] = {}
+    for key, item in pairs:
+        if key in value:
+            raise _DuplicateKeyError
+        value[key] = item
+    return value
+
+
+def _reject_constant(_value: str) -> None:
+    raise ValueError

ithrl/adapters/codex/__init__.py

@@ -0,0 +1,5 @@
+"""Parse supported Codex CLI rollout sessions."""
+
+from ithrl.adapters.codex.parser import PARSER
+
+__all__ = ["PARSER"]

ithrl/adapters/codex/context.py

@@ -0,0 +1,204 @@
+"""Compile editable context graphs from parsed Codex CLI sessions."""
+
+from __future__ import annotations
+
+from typing import cast
+
+from ithrl.adapters.contracts import NativeSession
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.context import (
+    MAX_CONTEXT_NODES,
+    ContextGraph,
+    ContextNode,
+    JsonObject,
+    JsonValue,
+    SourceRecordSelector,
+    content_digest,
+    stable_source_context_id,
+)
+from ithrl.decisions import DecisionSelector
+
+_HARNESS = "codex"
+_SOURCE = "source/rollout.jsonl"
+_CALL_TYPES = frozenset({"custom_tool_call", "function_call"})
+_OUTPUT_TYPES = frozenset({"custom_tool_call_output", "function_call_output"})
+_STRUCTURAL_RECORD_TYPES = frozenset({"session_meta", "turn_context", "world_state"})
+_OPAQUE_RECORD_TYPES = frozenset(
+    {
+        "inter_agent_communication_metadata",
+        "token_usage_record",
+        "world_state",
+    }
+)
+
+
+def compile_context(session: NativeSession, selector: DecisionSelector) -> ContextGraph:
+    """Build context preceding one selector produced from the parsed session."""
+
+    records = session.records
+    _validate_selector(session, selector, records)
+    context_count = selector.context_before_line - 1
+    if context_count > MAX_CONTEXT_NODES:
+        raise AdapterError(
+            AdapterErrorCode.CONTEXT_TOO_LARGE,
+            "selected decision has too many preceding context records",
+        )
+    return ContextGraph(nodes=_context_nodes(records[:context_count]))
+
+
+def source_selector(index: int, record: JsonObject) -> SourceRecordSelector:
+    """Return the stable native selector for one Codex JSONL record."""
+
+    ordinal = record.get("ordinal")
+    if type(ordinal) is int:
+        return SourceRecordSelector(
+            line=index + 1,
+            identity_key="ordinal",
+            identity_value=ordinal,
+        )
+    return SourceRecordSelector(line=index + 1)
+
+
+def opaque_prefix(records: tuple[JsonObject, ...]) -> tuple[bool, ...]:
+    """Track whether each source prefix contains frozen opaque context."""
+
+    prefixes = [False]
+    for record in records:
+        prefixes.append(prefixes[-1] or _is_opaque_record(record))
+    return tuple(prefixes)
+
+
+def _validate_selector(
+    session: NativeSession,
+    selector: DecisionSelector,
+    records: tuple[JsonObject, ...],
+) -> None:
+    index = selector.record.line - 1
+    if (
+        selector.harness != _HARNESS
+        or selector.session_id != session.metadata.session_id
+        or selector.source != _SOURCE
+        or index >= session.record_count
+    ):
+        raise AdapterError(
+            AdapterErrorCode.DECISION_NOT_FOUND,
+            "decision selector does not match the selected session",
+        )
+    record = records[index]
+    if selector.record != source_selector(
+        index, record
+    ) or selector.record_digest != content_digest(record):
+        raise AdapterError(
+            AdapterErrorCode.DECISION_NOT_FOUND,
+            "decision selector does not match the selected session",
+        )
+
+
+def _context_nodes(records: tuple[JsonObject, ...]) -> tuple[ContextNode, ...]:
+    nodes: list[ContextNode] = []
+    calls: dict[str, str] = {}
+    for index, record in enumerate(records):
+        record_type = cast(str, record["type"])
+        payload = _object(record.get("payload"))
+        kind = _context_kind(record_type, payload)
+        digest = content_digest(record)
+        selector = source_selector(index, record)
+        node_id = stable_source_context_id(
+            source=_SOURCE,
+            selector=selector,
+            kind=kind,
+            digest=digest,
+        )
+        nodes.append(
+            ContextNode(
+                id=node_id,
+                kind=kind,
+                selector=selector,
+                mutable=_is_mutable(record_type, payload),
+                protected=_is_protected(record_type, payload),
+                depends_on=_dependencies(record_type, payload, calls),
+                source=_SOURCE,
+                digest=digest,
+            )
+        )
+        _remember_call(record_type, payload, node_id, calls)
+    return tuple(nodes)
+
+
+def _context_kind(record_type: str, payload: JsonObject) -> str:
+    if record_type == "response_item" and (item_type := _string(payload.get("type"))):
+        return f"response_item.{item_type}"
+    if record_type == "event_msg" and (event_type := _string(payload.get("type"))):
+        return f"event_msg.{event_type}"
+    return record_type
+
+
+def _dependencies(
+    record_type: str,
+    payload: JsonObject,
+    calls: dict[str, str],
+) -> tuple[str, ...]:
+    item_type = _string(payload.get("type"))
+    call_id = _string(payload.get("call_id"))
+    if record_type == "response_item" and item_type in _OUTPUT_TYPES and call_id in calls:
+        return (calls[call_id],)
+    return ()
+
+
+def _remember_call(
+    record_type: str,
+    payload: JsonObject,
+    node_id: str,
+    calls: dict[str, str],
+) -> None:
+    item_type = _string(payload.get("type"))
+    call_id = _string(payload.get("call_id"))
+    if record_type == "response_item" and item_type in _CALL_TYPES and call_id is not None:
+        calls[call_id] = node_id
+
+
+def _is_mutable(record_type: str, payload: JsonObject) -> bool:
+    if record_type != "response_item":
+        return False
+    item_type = _string(payload.get("type"))
+    if item_type == "message":
+        return payload.get("role") in {"user", "assistant"}
+    return item_type in _CALL_TYPES or item_type in _OUTPUT_TYPES
+
+
+def _is_protected(record_type: str, payload: JsonObject) -> bool:
+    if record_type in _STRUCTURAL_RECORD_TYPES:
+        return True
+    return record_type == "event_msg" and payload.get("type") in {
+        "task_started",
+        "task_complete",
+    }
+
+
+def _is_opaque(kind: str) -> bool:
+    if kind in _OPAQUE_RECORD_TYPES:
+        return True
+    if kind.startswith("event_msg."):
+        return kind not in {"event_msg.task_started", "event_msg.task_complete"}
+    if kind.startswith("response_item."):
+        return kind.removeprefix("response_item.") not in {
+            "custom_tool_call",
+            "custom_tool_call_output",
+            "function_call",
+            "function_call_output",
+            "message",
+        }
+    return kind not in {"session_meta", "turn_context"}
+
+
+def _is_opaque_record(record: JsonObject) -> bool:
+    record_type = cast(str, record["type"])
+    return _is_opaque(_context_kind(record_type, _object(record.get("payload"))))
+
+
+def _object(value: JsonValue | None) -> JsonObject:
+    return value if isinstance(value, dict) else {}
+
+
+def _string(value: JsonValue | None) -> str | None:
+    return value if isinstance(value, str) and value else None