ithrl 0.1.0__py3-none-any.whl

ithrl/adapters/copilot/parser.py

@@ -0,0 +1,283 @@
+"""Validate the supported GitHub Copilot CLI session format."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Never, cast
+
+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, JsonValue
+from ithrl.timestamps import validate_rfc3339_timestamp
+
+_FORMAT_NAME = "copilot-events-jsonl"
+_PRODUCER = "copilot-agent"
+_SUPPORTED_RECORD_SCHEMA = 1
+
+
+@dataclass(frozen=True, slots=True)
+class _Record:
+    line: int
+    record_id: str
+    parent_id: str | None
+    record_type: str
+    data: JsonObject
+
+
+@dataclass(slots=True)
+class _ToolCall:
+    turn_id: str
+    started: bool = False
+    completed: bool = False
+
+
+@dataclass(slots=True)
+class _RelationshipState:
+    open_turns: dict[str, int] = field(default_factory=dict)
+    tools: dict[str, _ToolCall] = field(default_factory=dict)
+
+
+class _CopilotParser:
+    format_name = _FORMAT_NAME
+
+    def matches(self, document: JsonlDocument) -> bool:
+        """Return whether the first record has the Copilot session signature."""
+
+        if not document.records:
+            return False
+        first = document.records[0]
+        data = first.get("data")
+        return (
+            first.get("type") == "session.start"
+            and isinstance(data, dict)
+            and data.get("producer") == _PRODUCER
+            and "sessionId" in data
+            and "version" in data
+            and "copilotVersion" in data
+        )
+
+    def parse(self, document: JsonlDocument) -> NativeSession:
+        """Validate and preserve one bounded Copilot session document."""
+
+        if not self.matches(document):
+            raise AdapterError(
+                AdapterErrorCode.UNSUPPORTED_FORMAT,
+                "session source is not a GitHub Copilot CLI event log",
+            )
+
+        records = _validate_envelopes(document.records)
+        metadata = _parse_metadata(records)
+        _validate_turns_and_tools(records)
+        return NativeSession(
+            metadata=metadata,
+            source=document.source,
+            native_bytes=document.raw,
+            records=document.records,
+        )
+
+
+PARSER = _CopilotParser()
+
+
+def _validate_envelopes(records: tuple[JsonObject, ...]) -> tuple[_Record, ...]:
+    validated: list[_Record] = []
+    record_ids: set[str] = set()
+    for line, record in enumerate(records, start=1):
+        record_id = _required_string(record.get("id"), line, "session record ID is missing")
+        if record_id in record_ids:
+            _invalid("session record IDs must be unique", line)
+        record_ids.add(record_id)
+
+        parent = record.get("parentId")
+        if parent is not None and (not isinstance(parent, str) or not parent):
+            _invalid("session record parent ID must be a non-empty string or null", line)
+
+        timestamp = _required_string(
+            record.get("timestamp"), line, "session record timestamp is missing"
+        )
+        try:
+            validate_rfc3339_timestamp(timestamp, field="session record timestamp")
+        except ValueError:
+            raise AdapterError(
+                AdapterErrorCode.INVALID_SESSION,
+                "session record timestamp is not valid RFC 3339",
+                line=line,
+            ) from None
+        record_type = _required_string(record.get("type"), line, "session record type is missing")
+        data = record.get("data")
+        if not isinstance(data, dict):
+            _invalid("session record data must be an object", line)
+
+        validated.append(
+            _Record(
+                line=line,
+                record_id=record_id,
+                parent_id=parent,
+                record_type=record_type,
+                data=cast(JsonObject, data),
+            )
+        )
+    return tuple(validated)
+
+
+def _parse_metadata(records: tuple[_Record, ...]) -> SessionMetadata:
+    starts = [record for record in records if record.record_type == "session.start"]
+    if len(starts) != 1 or starts[0].line != 1:
+        _invalid("session must begin with exactly one session.start record", 1)
+    start = starts[0]
+
+    session_id = _required_string(start.data.get("sessionId"), start.line, "session ID is missing")
+    record_schema = start.data.get("version")
+    if type(record_schema) is not int or record_schema != _SUPPORTED_RECORD_SCHEMA:
+        raise AdapterError(
+            AdapterErrorCode.UNSUPPORTED_VERSION,
+            "GitHub Copilot CLI record schema is not supported",
+            line=start.line,
+        )
+    producer_version = _required_string(
+        start.data.get("copilotVersion"), start.line, "producer version is missing"
+    )
+    captured_at = _required_string(
+        start.data.get("startTime"), start.line, "session start time is missing"
+    )
+    try:
+        validate_rfc3339_timestamp(captured_at, field="session start time")
+    except ValueError:
+        raise AdapterError(
+            AdapterErrorCode.INVALID_SESSION,
+            "session start time is not valid RFC 3339",
+            line=start.line,
+        ) from None
+
+    return SessionMetadata(
+        format=SessionFormat(
+            harness="copilot",
+            name=_FORMAT_NAME,
+            producer_version=producer_version,
+            record_schema_version=record_schema,
+        ),
+        session_id=session_id,
+        captured_at=captured_at,
+    )
+
+
+def _validate_turns_and_tools(records: tuple[_Record, ...]) -> None:
+    state = _RelationshipState()
+    for record in records:
+        if validator := _RELATIONSHIP_VALIDATORS.get(record.record_type):
+            validator(record, state)
+
+
+def _start_turn(record: _Record, state: _RelationshipState) -> None:
+    turn_id = _turn_id(record)
+    state.open_turns[turn_id] = state.open_turns.get(turn_id, 0) + 1
+
+
+def _end_turn(record: _Record, state: _RelationshipState) -> None:
+    turn_id = _turn_id(record)
+    depth = state.open_turns.get(turn_id, 0)
+    if depth == 0:
+        _invalid("assistant turn ends before it starts", record.line)
+    if depth == 1:
+        del state.open_turns[turn_id]
+    else:
+        state.open_turns[turn_id] = depth - 1
+
+
+def _add_tool_requests(
+    record: _Record,
+    state: _RelationshipState,
+) -> None:
+    requests = record.data.get("toolRequests")
+    if requests is None:
+        return
+    if not isinstance(requests, list):
+        _invalid("assistant tool requests must be an array", record.line)
+    if not requests:
+        return
+
+    turn_id = _turn_id(record)
+    _require_open_turn(turn_id, record.line, state.open_turns)
+    for request in requests:
+        if not isinstance(request, dict):
+            _invalid("assistant tool request must be an object", record.line)
+        tool_call_id = _required_string(
+            request.get("toolCallId"), record.line, "assistant tool call ID is missing"
+        )
+        if tool_call_id in state.tools:
+            _invalid("assistant tool call IDs must be unique", record.line)
+        state.tools[tool_call_id] = _ToolCall(turn_id=turn_id)
+
+
+def _start_tool(
+    record: _Record,
+    state: _RelationshipState,
+) -> None:
+    tool_call_id = _required_string(
+        record.data.get("toolCallId"), record.line, "tool execution call ID is missing"
+    )
+    turn_id = _turn_id(record)
+    tool = state.tools.get(tool_call_id)
+    if tool is None:
+        _invalid("tool execution starts before its assistant request", record.line)
+    _require_open_turn(turn_id, record.line, state.open_turns)
+    if tool.turn_id != turn_id:
+        _invalid("tool execution and assistant request use different turns", record.line)
+    if tool.started:
+        _invalid("tool execution starts more than once", record.line)
+    tool.started = True
+
+
+def _complete_tool(
+    record: _Record,
+    state: _RelationshipState,
+) -> None:
+    tool_call_id = _required_string(
+        record.data.get("toolCallId"), record.line, "tool completion call ID is missing"
+    )
+    turn_id = _turn_id(record)
+    tool = state.tools.get(tool_call_id)
+    if tool is None or not tool.started:
+        _invalid("tool execution completes before it starts", record.line)
+    _require_open_turn(turn_id, record.line, state.open_turns)
+    if tool.turn_id != turn_id:
+        _invalid("tool completion and assistant request use different turns", record.line)
+    if tool.completed:
+        _invalid("tool execution completes more than once", record.line)
+    tool.completed = True
+
+
+def _require_open_turn(
+    turn_id: str,
+    line: int,
+    open_turns: dict[str, int],
+) -> None:
+    if not open_turns.get(turn_id, 0):
+        _invalid("tool relationship is outside its assistant turn", line)
+
+
+def _turn_id(record: _Record) -> str:
+    return _required_string(record.data.get("turnId"), record.line, "turn ID is missing")
+
+
+def _required_string(value: JsonValue | None, line: int, message: str) -> str:
+    if not isinstance(value, str) or not value:
+        _invalid(message, line)
+    return value
+
+
+def _invalid(message: str, line: int) -> Never:
+    raise AdapterError(AdapterErrorCode.INVALID_SESSION, message, line=line)
+
+
+type _RelationshipValidator = Callable[[_Record, _RelationshipState], None]
+
+_RELATIONSHIP_VALIDATORS: dict[str, _RelationshipValidator] = {
+    "assistant.turn_start": _start_turn,
+    "assistant.message": _add_tool_requests,
+    "tool.execution_start": _start_tool,
+    "tool.execution_complete": _complete_tool,
+    "assistant.turn_end": _end_turn,
+}

ithrl/adapters/discovery.py

@@ -0,0 +1,220 @@
+"""Bounded contracts and filesystem traversal for native session discovery."""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from ithrl.adapters.contracts import SourceFacts
+from ithrl.adapters.errors import AdapterError, AdapterErrorCode
+from ithrl.behavior import BehaviorType
+from ithrl.decisions import DecisionLimitation
+from ithrl.path_safety import UnsafePathError, validate_directory_chain
+from ithrl.timestamps import validate_rfc3339_timestamp
+
+type HarnessName = Literal["codex", "copilot"]
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryLimits:
+    """Resource limits for one read-only default-store scan."""
+
+    max_entries: int = 50_000
+    max_candidates: int = 4_096
+    max_parse_bytes: int = 512 * 1024 * 1024
+    max_sessions: int = 10
+
+    def __post_init__(self) -> None:
+        if (
+            min(
+                self.max_entries,
+                self.max_candidates,
+                self.max_parse_bytes,
+                self.max_sessions,
+            )
+            < 1
+        ):
+            raise ValueError("discovery limits must be positive")
+        if self.max_candidates > self.max_entries:
+            raise ValueError("max_candidates must not exceed max_entries")
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSource:
+    """One candidate native session file found under a known store."""
+
+    path: Path
+    modified_at_ns: int
+    size_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class SourceScan:
+    """A bounded set of matching source files from one native store."""
+
+    sources: tuple[SessionSource, ...]
+    truncated: bool
+
+
+class SessionSummary(BaseModel):
+    """Native session facts that can be shown without captured content."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
+
+    schema_version: Literal[1] = 1
+    harness: HarnessName
+    session_id: Annotated[str, Field(min_length=1, max_length=1024)]
+    producer_version: Annotated[str, Field(min_length=1, max_length=128)]
+    captured_at: Annotated[str, Field(min_length=1, max_length=64)]
+    decision_count: Annotated[int, Field(ge=1, le=4096)]
+    target_types: Annotated[tuple[BehaviorType, ...], Field(min_length=1, max_length=2)]
+    limitations: tuple[DecisionLimitation, ...] = ()
+
+    @field_validator("captured_at")
+    @classmethod
+    def validate_captured_at(cls, value: str) -> str:
+        return validate_rfc3339_timestamp(value, field="captured_at")
+
+    @model_validator(mode="after")
+    def validate_unique_values(self) -> SessionSummary:
+        if len(set(self.target_types)) != len(self.target_types):
+            raise ValueError("target_types must not contain duplicates")
+        if len(set(self.limitations)) != len(self.limitations):
+            raise ValueError("limitations must not contain duplicates")
+        return self
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredSession:
+    """A display-safe summary paired with its internal source path."""
+
+    source: SessionSource
+    summary: SessionSummary
+    source_facts: SourceFacts
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveryResult:
+    """Bounded supported sessions and scan counts that expose no session content."""
+
+    sessions: tuple[DiscoveredSession, ...]
+    candidates_seen: int
+    rejected_candidates: int
+    rejection_codes: tuple[AdapterErrorCode, ...]
+    truncated: bool
+
+
+def scan_store(
+    root: Path,
+    *,
+    max_depth: int,
+    accepts: Callable[[Path], bool],
+    limits: DiscoveryLimits,
+) -> SourceScan:
+    """Return matching regular files without following directory links."""
+
+    if max_depth < 0:
+        raise ValueError("max_depth must not be negative")
+    if not _store_is_available(root):
+        return SourceScan(sources=(), truncated=False)
+
+    candidates: list[SessionSource] = []
+    matching_entries = 0
+    for path, entry_metadata in _walk_store(
+        root,
+        max_depth=max_depth,
+        max_entries=limits.max_entries,
+    ):
+        if not accepts(path.relative_to(root)):
+            continue
+        matching_entries += 1
+        if stat.S_ISLNK(entry_metadata.st_mode) or not stat.S_ISREG(entry_metadata.st_mode):
+            raise AdapterError(
+                AdapterErrorCode.UNSAFE_SOURCE,
+                "native session candidate must be a regular file, not a link",
+            )
+        candidates.append(
+            SessionSource(
+                path=path,
+                modified_at_ns=entry_metadata.st_mtime_ns,
+                size_bytes=entry_metadata.st_size,
+            )
+        )
+        if len(candidates) == limits.max_candidates * 2:
+            candidates.sort(key=_source_sort_key)
+            del candidates[limits.max_candidates :]
+    candidates.sort(key=_source_sort_key)
+    del candidates[limits.max_candidates :]
+    return SourceScan(
+        sources=tuple(candidates),
+        truncated=matching_entries > len(candidates),
+    )
+
+
+def _store_is_available(root: Path) -> bool:
+    try:
+        metadata = root.lstat()
+    except FileNotFoundError:
+        return False
+    except OSError:
+        raise AdapterError(
+            AdapterErrorCode.SOURCE_UNAVAILABLE,
+            "native session store is unavailable",
+        ) from None
+    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
+        raise AdapterError(
+            AdapterErrorCode.UNSAFE_SOURCE,
+            "native session store must be a directory, not a link",
+        )
+    try:
+        validate_directory_chain(root)
+    except UnsafePathError:
+        raise AdapterError(
+            AdapterErrorCode.UNSAFE_SOURCE,
+            "native session store has an unsafe controlling directory",
+        ) from None
+    return True
+
+
+def _walk_store(
+    root: Path,
+    *,
+    max_depth: int,
+    max_entries: int,
+) -> Iterator[tuple[Path, os.stat_result]]:
+    pending = [(root, 0)]
+    entries_seen = 0
+    while pending:
+        directory, depth = pending.pop()
+        try:
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    entries_seen += 1
+                    if entries_seen > max_entries:
+                        raise AdapterError(
+                            AdapterErrorCode.DISCOVERY_LIMIT_EXCEEDED,
+                            "native session store exceeds the discovery entry limit",
+                        )
+                    entry_metadata = entry.stat(follow_symlinks=False)
+                    if stat.S_ISDIR(entry_metadata.st_mode):
+                        if depth < max_depth and not entry.is_symlink():
+                            pending.append((Path(entry.path), depth + 1))
+                        continue
+                    yield Path(entry.path), entry_metadata
+        except AdapterError:
+            raise
+        except OSError:
+            raise AdapterError(
+                AdapterErrorCode.SOURCE_UNAVAILABLE,
+                "native session store cannot be inspected",
+            ) from None
+
+
+def _source_sort_key(source: SessionSource) -> tuple[int, str]:
+    return -source.modified_at_ns, source.path.as_posix()

ithrl/adapters/errors.py

@@ -0,0 +1,52 @@
+"""Stable native-session errors that do not expose captured content."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class AdapterErrorCode(StrEnum):
+    """Machine-readable reasons native session evidence cannot be used."""
+
+    SOURCE_UNAVAILABLE = "source-unavailable"
+    UNSAFE_SOURCE = "unsafe-source"
+    SOURCE_TOO_LARGE = "source-too-large"
+    LINE_TOO_LARGE = "line-too-large"
+    TOO_MANY_RECORDS = "too-many-records"
+    INVALID_UTF8 = "invalid-utf8"
+    INVALID_JSONL = "invalid-jsonl"
+    DUPLICATE_KEY = "duplicate-key"
+    JSON_LIMIT_EXCEEDED = "json-limit-exceeded"
+    SOURCE_CHANGED = "source-changed"
+    UNSUPPORTED_FORMAT = "unsupported-format"
+    AMBIGUOUS_FORMAT = "ambiguous-format"
+    UNSUPPORTED_VERSION = "unsupported-version"
+    INVALID_SESSION = "invalid-session"
+    CONTEXT_TOO_LARGE = "context-too-large"
+    DECISION_NOT_FOUND = "decision-not-found"
+    TARGET_NOT_FOUND = "target-not-found"
+    TOO_MANY_DECISIONS = "too-many-decisions"
+    DISCOVERY_LIMIT_EXCEEDED = "discovery-limit-exceeded"
+    SESSION_NOT_FOUND = "session-not-found"
+    AMBIGUOUS_SESSION = "ambiguous-session"
+    NO_SESSIONS = "no-sessions"
+
+
+class AdapterError(ValueError):
+    """Native session evidence cannot be read, validated, or selected safely."""
+
+    __slots__ = ("bytes_read", "code", "line")
+
+    def __init__(
+        self,
+        code: AdapterErrorCode,
+        message: str,
+        *,
+        line: int | None = None,
+        bytes_read: int = 0,
+    ) -> None:
+        self.code = code
+        self.line = line
+        self.bytes_read = bytes_read
+        location = f" at line {line}" if line is not None else ""
+        super().__init__(f"{message}{location}")