ithrl 0.1.0__py3-none-any.whl

ithrl/adapters/codex/decisions.py

@@ -0,0 +1,224 @@
+"""Enumerate completed decisions from parsed Codex CLI sessions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import cast
+
+from ithrl.adapters.codex.context import opaque_prefix, source_selector
+from ithrl.adapters.contracts import NativeSession
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.behavior import BehaviorObservation, FinalResponseTarget
+from ithrl.context import JsonObject, JsonValue, content_digest
+from ithrl.decisions import (
+    MAX_DECISIONS,
+    DecisionCaseFacts,
+    DecisionDraft,
+    DecisionLimitation,
+    DecisionSelector,
+    TargetCandidate,
+)
+
+_ADAPTER = "codex-session"
+_ADAPTER_VERSION = "1"
+_HARNESS = "codex"
+_SOURCE = "source/rollout.jsonl"
+_MAX_BEHAVIOR_BYTES = 64 * 1024
+_OUTPUT_TYPES = frozenset({"custom_tool_call_output", "function_call_output"})
+
+
+@dataclass(frozen=True, slots=True)
+class _DecisionRecord:
+    index: int
+    context_before_line: int
+    turn_id: str
+    kind: str
+    native_id: str
+    observation: BehaviorObservation
+    targets: tuple[TargetCandidate, ...]
+    model: str | None
+
+
+def enumerate_decisions(session: NativeSession) -> tuple[DecisionDraft, ...]:
+    """Return supported decisions whose enclosing Codex task completed."""
+
+    if session.metadata.format.harness != _HARNESS:
+        raise ValueError("native session is not a Codex CLI session")
+
+    records = session.records
+    decisions = _completed_decision_records(records)
+    opaque_context = opaque_prefix(records)
+    provider = _provider(records)
+    return tuple(
+        _build_draft(session, records, opaque_context, provider, decision) for decision in decisions
+    )
+
+
+def _completed_decision_records(records: tuple[JsonObject, ...]) -> tuple[_DecisionRecord, ...]:
+    turn_models: dict[str, str] = {}
+    open_turns: dict[str, list[int]] = {}
+    decisions: list[_DecisionRecord] = []
+    latest_model_input_line = 0
+
+    for index, record in enumerate(records):
+        record_type = _string(record.get("type"))
+        payload = _object(record.get("payload"))
+        if record_type == "turn_context":
+            _remember_turn_model(payload, turn_models)
+            continue
+        if record_type == "response_item" and _is_model_input(payload):
+            latest_model_input_line = index + 2
+            continue
+        if record_type != "event_msg":
+            continue
+        event_type = _string(payload.get("type"))
+        turn_id = _string(payload.get("turn_id"))
+        if turn_id is None:
+            continue
+        if event_type == "task_started":
+            open_turns.setdefault(turn_id, []).append(index + 2)
+            continue
+        if event_type != "task_complete" or not (starts := open_turns.get(turn_id)):
+            continue
+        # Codex task IDs can overlap; a completion closes the latest unmatched start for that ID.
+        context_before_line = max(starts.pop(), latest_model_input_line)
+        if not starts:
+            del open_turns[turn_id]
+        decision = _final_response_record(
+            record,
+            index=index,
+            turn_id=turn_id,
+            context_before_line=context_before_line,
+            model=turn_models.get(turn_id),
+        )
+        if decision is None:
+            continue
+        if len(decisions) == MAX_DECISIONS:
+            raise AdapterError(
+                AdapterErrorCode.TOO_MANY_DECISIONS,
+                "session contains too many completed decisions",
+            )
+        decisions.append(decision)
+
+    return tuple(decisions)
+
+
+def _remember_turn_model(payload: JsonObject, models: dict[str, str]) -> None:
+    turn_id = _string(payload.get("turn_id"))
+    model = _bounded_string(payload.get("model"), 256)
+    if turn_id is not None and model is not None:
+        models[turn_id] = model
+
+
+def _final_response_record(
+    record: JsonObject,
+    *,
+    index: int,
+    turn_id: str,
+    context_before_line: int,
+    model: str | None,
+) -> _DecisionRecord | None:
+    payload = _object(record.get("payload"))
+    text = _bounded_behavior_text(payload.get("last_agent_message"))
+    if text is None:
+        return None
+
+    target = FinalResponseTarget(text_equals=text)
+    return _DecisionRecord(
+        index=index,
+        context_before_line=context_before_line,
+        turn_id=turn_id,
+        kind="codex-task-complete",
+        native_id=turn_id,
+        observation=BehaviorObservation(final_response=text),
+        targets=(_target_candidate(target),),
+        model=model,
+    )
+
+
+def _is_model_input(payload: JsonObject) -> bool:
+    item_type = _string(payload.get("type"))
+    return (
+        item_type == "message" and payload.get("role") in {"user", "developer", "system"}
+    ) or item_type in _OUTPUT_TYPES
+
+
+def _bounded_behavior_text(value: JsonValue | None) -> str | None:
+    if not isinstance(value, str) or not value:
+        return None
+    return value if len(value.encode("utf-8")) <= _MAX_BEHAVIOR_BYTES else None
+
+
+def _target_candidate(target: FinalResponseTarget) -> TargetCandidate:
+    return TargetCandidate(
+        ordinal=1,
+        target=target,
+        evidence_support="supported",
+        experimental_support="unvalidated",
+    )
+
+
+def _build_draft(
+    session: NativeSession,
+    records: tuple[JsonObject, ...],
+    opaque_prefix: tuple[bool, ...],
+    provider: str | None,
+    decision: _DecisionRecord,
+) -> DecisionDraft:
+    record = records[decision.index]
+    limitations: list[DecisionLimitation] = ["experimental-support-unvalidated"]
+    if opaque_prefix[decision.context_before_line - 1]:
+        limitations.append("opaque-context-frozen")
+    return DecisionDraft(
+        case=DecisionCaseFacts(
+            adapter=_ADAPTER,
+            adapter_version=_ADAPTER_VERSION,
+            provider=provider,
+            model_requested=decision.model,
+            source_schema=session.metadata.format.name,
+        ),
+        selector=_selector(session, record, decision),
+        observed_at=cast(str, record["timestamp"]),
+        observation=decision.observation,
+        targets=decision.targets,
+        limitations=tuple(limitations),
+    )
+
+
+def _selector(
+    session: NativeSession,
+    record: JsonObject,
+    decision: _DecisionRecord,
+) -> DecisionSelector:
+    return DecisionSelector(
+        harness=_HARNESS,
+        session_id=session.metadata.session_id,
+        turn_id=decision.turn_id,
+        kind=decision.kind,
+        native_id=decision.native_id,
+        source=_SOURCE,
+        context_before_line=decision.context_before_line,
+        record=source_selector(decision.index, record),
+        record_digest=content_digest(record),
+    )
+
+
+def _provider(records: tuple[JsonObject, ...]) -> str | None:
+    if not records:
+        return None
+    first = records[0]
+    if first.get("type") != "session_meta":
+        return None
+    return _bounded_string(_object(first.get("payload")).get("model_provider"), 256)
+
+
+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
+
+
+def _bounded_string(value: JsonValue | None, limit: int) -> str | None:
+    return value if isinstance(value, str) and 0 < len(value) <= limit else None

ithrl/adapters/codex/discovery.py

@@ -0,0 +1,60 @@
+"""Find Codex rollout sessions in an ordinary local store."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ithrl.adapters.discovery import DiscoveryLimits, SourceScan, scan_store
+
+_STORE_DEPTH = 3
+
+
+def discover_sources(
+    *,
+    root: Path | None = None,
+    limits: DiscoveryLimits | None = None,
+    session_id: str | None = None,
+) -> SourceScan:
+    """Return recent Codex rollout files from a local session store."""
+
+    selected_limits = limits or DiscoveryLimits()
+    return scan_store(
+        root if root is not None else _default_store(),
+        max_depth=_STORE_DEPTH,
+        accepts=lambda path: (
+            _is_rollout_path(path)
+            and (session_id is None or path.name.endswith(f"-{session_id}.jsonl"))
+        ),
+        limits=selected_limits,
+    )
+
+
+def _default_store() -> Path:
+    codex_home = os.environ.get("CODEX_HOME")
+    if codex_home:
+        return Path(codex_home).expanduser() / "sessions"
+    return Path.home() / ".codex" / "sessions"
+
+
+def _is_rollout_path(path: Path) -> bool:
+    parts = path.parts
+    if len(parts) != 4:
+        return False
+    year, month, day, filename = parts
+    return all(
+        (
+            _is_ascii_number(year, width=4),
+            _is_ascii_number(month, width=2),
+            _is_ascii_number(day, width=2),
+            _is_rollout_filename(filename),
+        )
+    )
+
+
+def _is_ascii_number(value: str, *, width: int) -> bool:
+    return len(value) == width and value.isascii() and value.isdigit()
+
+
+def _is_rollout_filename(value: str) -> bool:
+    return value.startswith("rollout-") and value != "rollout-.jsonl" and value.endswith(".jsonl")

ithrl/adapters/codex/parser.py

@@ -0,0 +1,191 @@
+"""Validate Codex rollout JSONL that starts with `session_meta`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Never
+
+from ithrl.adapters._jsonl import JsonlDocument
+from ithrl.adapters.contracts import NativeSession, SessionFormat, SessionMetadata
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.context import JsonObject
+from ithrl.timestamps import validate_rfc3339_timestamp
+
+_FORMAT_NAME = "codex-rollout-jsonl"
+_CALL_OUTPUT_TYPES = {
+    "custom_tool_call": "custom_tool_call_output",
+    "function_call": "function_call_output",
+}
+_OUTPUT_TYPES = frozenset({"custom_tool_call_output", "function_call_output"})
+
+
+@dataclass(frozen=True, slots=True)
+class _Record:
+    line: int
+    timestamp: datetime
+    type: str
+    payload: JsonObject
+
+
+class _CodexSessionParser:
+    format_name = _FORMAT_NAME
+
+    def matches(self, document: JsonlDocument) -> bool:
+        """Return whether the document has the observed Codex rollout signature."""
+
+        if not document.records:
+            return False
+        first = document.records[0]
+        payload = first.get("payload")
+        return (
+            first.get("type") == "session_meta"
+            and isinstance(payload, dict)
+            and "cli_version" in payload
+            and ("id" in payload or "session_id" in payload)
+        )
+
+    def parse(self, document: JsonlDocument) -> NativeSession:
+        """Validate and preserve one supported Codex rollout document."""
+
+        if not self.matches(document):
+            raise AdapterError(
+                AdapterErrorCode.UNSUPPORTED_FORMAT,
+                "session source is not a Codex rollout",
+            )
+
+        records = _validate_envelopes(document.records)
+        metadata = _session_metadata(records)
+        _validate_response_items(records)
+        return NativeSession(
+            metadata=metadata,
+            source=document.source,
+            native_bytes=document.raw,
+            records=document.records,
+        )
+
+
+PARSER = _CodexSessionParser()
+
+
+def _validate_envelopes(records: tuple[JsonObject, ...]) -> tuple[_Record, ...]:
+    validated: list[_Record] = []
+    for line, record in enumerate(records, start=1):
+        ordinal = record.get("ordinal")
+        if ordinal is not None and (type(ordinal) is not int or ordinal < 0):
+            _invalid("Codex record ordinal must be a non-negative integer when present", line)
+
+        timestamp_text = _required_string(record, "timestamp", line, "record timestamp")
+        timestamp = _parse_timestamp(timestamp_text, line, "record timestamp")
+
+        record_type = _required_string(record, "type", line, "record type")
+        payload = record.get("payload")
+        if not isinstance(payload, dict):
+            _invalid("Codex record payload must be an object", line)
+
+        validated.append(_Record(line=line, timestamp=timestamp, type=record_type, payload=payload))
+    return tuple(validated)
+
+
+def _session_metadata(records: tuple[_Record, ...]) -> SessionMetadata:
+    record = records[0]
+    if record.type != "session_meta":
+        _invalid("Codex session metadata must be the first record")
+    source_session_id = _required_string(
+        record.payload,
+        "id",
+        record.line,
+        "source session identifier",
+    )
+    _required_string(record.payload, "session_id", record.line, "session family identifier")
+
+    captured_at = _required_string(record.payload, "timestamp", record.line, "capture timestamp")
+    _parse_timestamp(captured_at, record.line, "capture timestamp")
+
+    producer_version = _required_string(
+        record.payload,
+        "cli_version",
+        record.line,
+        "producer version",
+    )
+
+    return SessionMetadata(
+        format=SessionFormat(
+            harness="codex",
+            name=_FORMAT_NAME,
+            producer_version=producer_version,
+        ),
+        session_id=source_session_id,
+        captured_at=captured_at,
+    )
+
+
+def _validate_response_items(records: tuple[_Record, ...]) -> None:
+    item_ids: set[str] = set()
+    calls: dict[str, str] = {}
+    outputs: set[str] = set()
+
+    for record in records:
+        if record.type != "response_item":
+            continue
+        item_type = _required_string(record.payload, "type", record.line, "response item type")
+        item_id = _required_string(record.payload, "id", record.line, "response item identifier")
+        if item_id in item_ids:
+            _invalid("Codex response item identifiers must be unique", record.line)
+        item_ids.add(item_id)
+
+        _validate_tool_relationship(record, item_type, calls, outputs)
+
+
+def _validate_tool_relationship(
+    record: _Record,
+    item_type: str,
+    calls: dict[str, str],
+    outputs: set[str],
+) -> None:
+    expected_output = _CALL_OUTPUT_TYPES.get(item_type)
+    if expected_output is not None:
+        call_id = _required_string(record.payload, "call_id", record.line, "tool call identifier")
+        if call_id in calls:
+            _invalid("Codex tool call identifiers must be unique", record.line)
+        calls[call_id] = expected_output
+        return
+    if item_type not in _OUTPUT_TYPES:
+        return
+
+    call_id = _required_string(record.payload, "call_id", record.line, "tool call identifier")
+    if call_id not in calls:
+        _invalid("Codex tool output must follow its call", record.line)
+    if item_type != calls[call_id]:
+        _invalid("Codex tool output type must match its call type", record.line)
+    if call_id in outputs:
+        _invalid("Codex tool calls must have at most one output", record.line)
+    outputs.add(call_id)
+
+
+def _required_string(
+    value: JsonObject,
+    field: str,
+    line: int,
+    description: str,
+) -> str:
+    item = value.get(field)
+    if not isinstance(item, str) or not item:
+        _invalid(f"Codex {description} must be a non-empty string", line)
+    return item
+
+
+def _parse_timestamp(value: str, line: int, description: str) -> datetime:
+    try:
+        validate_rfc3339_timestamp(value, field=description)
+        return datetime.fromisoformat(f"{value[:-1]}+00:00" if value.endswith("Z") else value)
+    except ValueError:
+        raise AdapterError(
+            AdapterErrorCode.INVALID_SESSION,
+            f"Codex {description} must be a valid RFC 3339 timestamp",
+            line=line,
+        ) from None
+
+
+def _invalid(message: str, line: int | None = None) -> Never:
+    raise AdapterError(AdapterErrorCode.INVALID_SESSION, message, line=line)

ithrl/adapters/contracts.py

@@ -0,0 +1,106 @@
+"""Harness-independent contracts for parsed native session evidence."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+from dataclasses import dataclass
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ithrl.context import JsonObject
+from ithrl.timestamps import validate_rfc3339_timestamp
+
+
+@dataclass(frozen=True, slots=True)
+class ParsingLimits:
+    """Resource limits applied before native session evidence is accepted."""
+
+    max_bytes: int = 64 * 1024 * 1024
+    max_line_bytes: int = 8 * 1024 * 1024
+    max_records: int = 250_000
+    max_json_items: int = 1_000_000
+
+    def __post_init__(self) -> None:
+        if min(self.max_bytes, self.max_line_bytes, self.max_records, self.max_json_items) < 1:
+            raise ValueError("parsing limits must be positive")
+        if self.max_line_bytes > self.max_bytes:
+            raise ValueError("max_line_bytes must not exceed max_bytes")
+
+
+class _ImmutableContract(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+
+class SessionFormat(_ImmutableContract):
+    """Identity and producer metadata for one native saved-session format."""
+
+    schema_version: Literal[1] = 1
+    harness: Annotated[str, Field(min_length=1, max_length=64)]
+    name: Annotated[str, Field(min_length=1, max_length=128)]
+    producer_version: Annotated[str, Field(min_length=1, max_length=128)]
+    record_schema_version: int | str | None = None
+
+
+class SessionMetadata(_ImmutableContract):
+    """Shared facts needed to identify parsed native evidence."""
+
+    schema_version: Literal[1] = 1
+    format: SessionFormat
+    session_id: Annotated[str, Field(min_length=1, max_length=1024)]
+    captured_at: Annotated[str, Field(min_length=1, max_length=64)]
+
+    @field_validator("captured_at")
+    @classmethod
+    def validate_captured_at(cls, value: str) -> str:
+        return validate_rfc3339_timestamp(value, field="captured_at")
+
+
+class SourceFacts(_ImmutableContract):
+    """Content identity of the exact native source bytes that were parsed."""
+
+    schema_version: Literal[1] = 1
+    sha256: Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
+    size_bytes: Annotated[int, Field(ge=1)]
+
+
+class NativeSession:
+    """Parsed metadata with an unchanged native JSONL snapshot."""
+
+    __slots__ = ("_native_bytes", "_records", "metadata", "source")
+
+    def __init__(
+        self,
+        *,
+        metadata: SessionMetadata,
+        source: SourceFacts,
+        native_bytes: bytes,
+        records: tuple[JsonObject, ...],
+    ) -> None:
+        if not native_bytes or not records:
+            raise ValueError("native session evidence must not be empty")
+        if source.size_bytes != len(native_bytes):
+            raise ValueError("native session byte count does not match source facts")
+        if source.sha256 != hashlib.sha256(native_bytes).hexdigest():
+            raise ValueError("native session digest does not match source facts")
+        self.metadata = metadata
+        self.source = source
+        self._native_bytes = native_bytes
+        self._records = copy.deepcopy(records)
+
+    @property
+    def native_bytes(self) -> bytes:
+        """Return the exact bytes read from the native session file."""
+
+        return self._native_bytes
+
+    @property
+    def records(self) -> tuple[JsonObject, ...]:
+        """Return defensive copies of native records in source order."""
+
+        return copy.deepcopy(self._records)
+
+    @property
+    def record_count(self) -> int:
+        return len(self._records)

ithrl/adapters/copilot/__init__.py

@@ -0,0 +1,5 @@
+"""Parse GitHub Copilot CLI session event logs."""
+
+from ithrl.adapters.copilot.parser import PARSER
+
+__all__ = ["PARSER"]