Class TranscriptReader

src/agent/transcript.py:243–316

Replay companion for ``resume_agent_background`` (Chunk F / WI-7.4). Reads the JSONL transcript line-by-line, parsing each into a Python object (typically a dict mirroring the original ``asdict(Message)`` payload). Callers with a typed Message hierarchy can hydrate the dicts back in

class TranscriptReader:
    """Replay companion for ``resume_agent_background`` (Chunk F / WI-7.4).

    Reads the JSONL transcript line-by-line, parsing each into a Python
    object (typically a dict mirroring the original ``asdict(Message)``
    payload). Callers with a typed Message hierarchy can hydrate the
    dicts back into ``AssistantMessage``/``UserMessage`` etc. via their
    own factories — this reader stays loose-typed to avoid a cycle
    between the agent module and the transcript module.

    Tolerant of:
    * **Missing file** — yields nothing rather than raising.
    * **Trailing partial line** — log-once-and-skip rather than poison
      the entire history. Mirrors the chapter §"Mailbox" approach.
    * **Embedded blank lines** — skipped.

    Defining the reader here (per critic concern C6) so Chunk F's
    ``resume_agent_background`` SOLID DIP claim has a real interface
    to depend on rather than the writer's IO layer.
    """

    def __init__(self, path: str | Path) -> None:
        self._path = str(path)
        self._logged_partial = False

    @property
    def path(self) -> str:
        return self._path

    def __iter__(self) -> Iterator[Any]:
        return self._iterate()

    def _iterate(self) -> Iterator[Any]:
        """Yield one parsed object per line; skip blank/unparseable lines."""
        try:
            handle = open(self._path, "rb")
        except FileNotFoundError:
            return
        try:
            for raw_line in handle:
                # raw_line still has its trailing newline; strip and skip
                # blanks. Decode is utf-8 with replacement so a corrupt
                # byte doesn't crash the iterator.
                #
                # N2 caveat (Chunk-D fold-in): ``errors="replace"`` maps
                # corrupt bytes to U+FFFD. In theory a corrupted line
                # could still parse as JSON if the U+FFFD substitutions
                # land inside string literals — yielding "garbage but
                # technically valid JSON". For chapter-10 transcripts
                # the writer is the only producer and uses utf-8
                # round-trip, so the regime is safe; downstream replay
                # consumers should validate message shape post-parse.
                line = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
                if not line:
                    continue
                try:
                    yield json.loads(line)
                except json.JSONDecodeError: