feat: ADR 0032 M2-T001 — event-stream reader for evidence (additive)

Adds the read side of the spine so evidence builders can fold over typed
RunEvents. Inverse mapper audit_event_to_run_event_type returns None for
legacy/unmapped audit events (tool_call_started, model_route, git_sandbox_*)
rather than raising; read_run_events_from_audit / read_run_events_from_jsonl
yield only typed M0 lifecycle events with monotonic seq, passing payloads
through unchanged to preserve redaction.

Strictly additive: no evidence/receipt builder is switched to this reader yet
(M2-T002/T003; plan §13.4 forbids switching the receipt default before a
parity assertion exists).

Constraint: additive only, zero behavior change; legacy events skipped not errored; redaction preserved
Tested: lifecycle 22 (8 new), run_evidence + summary 26 unchanged, smoke 200, full mypy clean 1009 files, ruff check+format clean, docs validator 0 errors
Confidence: high
Roadmap-Status: unchanged

Author: johnteee

teaagent/_lazy_exports.py

@@ -167,6 +167,12 @@
     'RunCancelledError': ('teaagent.errors', 'RunCancelledError'),
     'RunEvent': ('teaagent.runner', 'RunEvent'),
     'RunEventType': ('teaagent.runner', 'RunEventType'),
+    'audit_event_to_run_event_type': (
+        'teaagent.runner',
+        'audit_event_to_run_event_type',
+    ),
+    'read_run_events_from_audit': ('teaagent.runner', 'read_run_events_from_audit'),
+    'read_run_events_from_jsonl': ('teaagent.runner', 'read_run_events_from_jsonl'),
     'RunRollup': ('teaagent.daily', 'RunRollup'),
     'RunStore': ('teaagent.run_store', 'RunStore'),
     'RunSummary': ('teaagent.run_store', 'RunSummary'),
@@ -291,6 +297,7 @@
         'teaagent.external_backends',
         'register_code_parse_backend',
     ),
+    'register_audit_consumer': ('teaagent.runner', 'register_audit_consumer'),
     'register_git_tools': ('teaagent.workspace_tools', 'register_git_tools'),
     'register_hybrid_backend': ('teaagent.hybrid_search', 'register_hybrid_backend'),
     'register_knowledge_backend': (

teaagent/runner/__init__.py

@@ -1,7 +1,15 @@
 """Agent runner package — decision loop, budget, and approval integration."""
 
 from ._core import AgentRunner, validate_tool_decision
-from ._events import EventSpine, RunEvent, RunEventType, register_audit_consumer
+from ._events import (
+    EventSpine,
+    RunEvent,
+    RunEventType,
+    audit_event_to_run_event_type,
+    read_run_events_from_audit,
+    read_run_events_from_jsonl,
+    register_audit_consumer,
+)
 from ._types import (
     ApprovalHandler,
     ApprovalRequest,
@@ -22,6 +30,9 @@
     'DecisionFn',
     'EventSpine',
     'FinalAnswer',
+    'audit_event_to_run_event_type',
+    'read_run_events_from_audit',
+    'read_run_events_from_jsonl',
     'register_audit_consumer',
     'RunEvent',
     'RunEventType',

teaagent/runner/_events.py

@@ -19,9 +19,12 @@
 
 from __future__ import annotations
 
+import json
 import logging
+from collections.abc import Iterable
 from dataclasses import dataclass
 from enum import Enum
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, Callable, Mapping
 
 if TYPE_CHECKING:
@@ -102,6 +105,27 @@ def run_event_to_audit_event_type(event_type: RunEventType) -> str:
     return audit_type
 
 
+# Inverse mapping: audit event type string to RunEventType
+_AUDIT_EVENT_TO_RUN_EVENT_TYPE: dict[str, RunEventType] = {
+    v: k for k, v in _RUN_EVENT_TO_AUDIT_EVENT_TYPE.items()
+}
+
+
+def audit_event_to_run_event_type(audit_type: str) -> RunEventType | None:
+    """Map an audit event type string to a ``RunEventType``, or None if unmapped.
+
+    Legacy and unmapped audit event types (e.g. 'tool_call_started', 'model_route',
+    'git_sandbox_started') return None and are safely skipped by the reader.
+
+    Args:
+        audit_type: The audit event type string (from JSONL entry).
+
+    Returns:
+        The corresponding RunEventType, or None if not in the M0 set.
+    """
+    return _AUDIT_EVENT_TO_RUN_EVENT_TYPE.get(audit_type)
+
+
 class EventSpine:
     """Synchronous, in-process event bus for run-lifecycle events.
 
@@ -190,6 +214,86 @@ def emit(
                 )
 
 
+def read_run_events_from_audit(
+    entries: Iterable[Mapping[str, Any]],
+) -> list[RunEvent]:
+    """Convert audit JSONL entries to typed RunEvents.
+
+    Iterates over audit event dicts (already-parsed from JSONL), converts
+    those with mapped event types to RunEvents, and skips legacy/unmapped
+    event types. Sequence numbers are 1-based and monotonic over yielded events.
+
+    Redaction is preserved: payloads are passed through as-is from the audit
+    entries without reconstruction or un-redaction.
+
+    Args:
+        entries: An iterable of audit event dicts (from parsed JSONL lines).
+                 Expected keys: event_type, run_id, payload.
+
+    Returns:
+        A list of RunEvent objects in order, with seq 1..N monotonic.
+    """
+    events: list[RunEvent] = []
+    seq = 0
+
+    for entry in entries:
+        audit_type = entry.get('event_type')
+        if audit_type is None:
+            continue
+        run_event_type = audit_event_to_run_event_type(audit_type)
+
+        # Skip entries whose event_type does not map to RunEventType
+        if run_event_type is None:
+            continue
+
+        seq += 1
+        run_id = entry.get('run_id', '')
+        payload = entry.get('payload', {})
+
+        # Construct a RunEvent with the mapped type, run_id, payload, and seq.
+        event = RunEvent(
+            type=run_event_type,
+            run_id=run_id,
+            payload=payload,
+            seq=seq,
+        )
+        events.append(event)
+
+    return events
+
+
+def read_run_events_from_jsonl(path: str | Path) -> list[RunEvent]:
+    """Read a JSONL audit file and convert it to RunEvents.
+
+    Opens the file, parses each non-empty line as JSON, delegates to
+    read_run_events_from_audit, and returns the typed event list.
+
+    Tolerates blank lines and preserves redaction.
+
+    Args:
+        path: Path to the JSONL audit file.
+
+    Returns:
+        A list of RunEvent objects extracted from the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        json.JSONDecodeError: If a non-empty line is not valid JSON.
+    """
+    path_obj = Path(path) if isinstance(path, str) else path
+    entries: list[Mapping[str, Any]] = []
+
+    with open(path_obj, encoding='utf-8') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                # Tolerate blank lines
+                continue
+            entries.append(json.loads(line))
+
+    return read_run_events_from_audit(entries)
+
+
 def register_audit_consumer(spine: EventSpine, audit: AuditLogger) -> None:
     """Register an ``AuditLogger`` as an ``EventSpine`` consumer (ADR 0032 M1).