agent-session-otel 0.2.0__py3-none-any.whl

agent_session_otel/__init__.py

@@ -0,0 +1,10 @@
+"""agent-session-otel: normalize local Claude Code / Codex session logs into
+OpenTelemetry GenAI-compatible traces."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .schema import EventType, NormalizedEvent
+
+__all__ = ["__version__", "EventType", "NormalizedEvent"]

agent_session_otel/adapters/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .base import SessionAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+
+ADAPTERS = {
+    ClaudeCodeAdapter.vendor: ClaudeCodeAdapter(),
+    CodexAdapter.vendor: CodexAdapter(),
+}
+
+__all__ = ["SessionAdapter", "ClaudeCodeAdapter", "CodexAdapter", "ADAPTERS"]

agent_session_otel/adapters/base.py

@@ -0,0 +1,128 @@
+"""Adapter interface shared by all vendor-specific parsers."""
+
+from __future__ import annotations
+
+import abc
+import json
+from pathlib import Path
+from typing import Iterator
+
+from ..schema import EventType, NormalizedEvent
+
+
+class SessionAdapter(abc.ABC):
+    """Parses one vendor's session JSONL format into NormalizedEvent objects.
+
+    Adapters must never raise on malformed input: a line that fails to
+    parse as JSON, or a record whose shape doesn't match what the adapter
+    expects, is turned into an ``EventType.UNKNOWN`` event carrying the
+    original text/record so nothing is silently dropped. One bad line does
+    not lose the rest of an otherwise-recoverable session, and a file that
+    can't be opened at all (permissions, mid-write on some platforms,
+    disappeared between discovery and parsing) becomes a single UNKNOWN
+    event instead of an unhandled exception.
+
+    Files are streamed line-by-line rather than loaded into memory. Real
+    session logs -- especially Codex rollouts after heavy compaction --
+    have been observed in the hundreds of MB to low GB range.
+    """
+
+    vendor: str
+
+    @abc.abstractmethod
+    def discover(self, roots=None):
+        """Return a list of session files for this vendor."""
+
+    def resolve_session_id(self, path: Path, first_line: str) -> str:
+        """Determine the one session id used for every event parsed from
+        ``path``, given only its first non-empty line. Default: the
+        filename stem. Adapters whose filenames don't reliably match the
+        vendor's own session/thread id (e.g. Codex's
+        ``rollout-<timestamp>-<uuid>.jsonl``) should override this so that
+        every event from one file lands in the same exported trace.
+
+        Only the first line is available (not the whole file) so that
+        resolving a session id never requires a second full read of a
+        potentially multi-GB file.
+        """
+
+        return path.stem
+
+    def parse_file(self, path: Path) -> Iterator[NormalizedEvent]:
+        path = Path(path)
+        try:
+            fh = path.open("r", encoding="utf-8", errors="replace")
+        except OSError as exc:
+            yield NormalizedEvent(
+                vendor=self.vendor,
+                event_type=EventType.UNKNOWN,
+                session_id=path.stem,
+                source_file=str(path),
+                raw_type="_unreadable_file",
+                extra={"error": str(exc)},
+            )
+            return
+
+        try:
+            first_line = ""
+            for probe in fh:
+                stripped = probe.strip()
+                if stripped:
+                    first_line = stripped
+                    break
+            # Always safe: seeking to 0 on a text file is well-defined even
+            # after partial iteration (unlike seeking to an arbitrary tell()
+            # offset captured mid-iteration, which text-mode files forbid).
+            fh.seek(0)
+            try:
+                session_id = self.resolve_session_id(path, first_line)
+            except Exception:  # noqa: BLE001 - never let session-id resolution crash the parse
+                session_id = path.stem
+            if not session_id:
+                session_id = path.stem
+
+            for lineno, raw_line in enumerate(fh, start=1):
+                line = raw_line.strip()
+                if not line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError as exc:
+                    yield NormalizedEvent(
+                        vendor=self.vendor,
+                        event_type=EventType.UNKNOWN,
+                        session_id=session_id,
+                        source_file=str(path),
+                        raw_type="_invalid_json",
+                        line_number=lineno,
+                        extra={"parse_error": str(exc)},
+                        raw={"raw_line": line[:4000]},
+                    )
+                    continue
+
+                try:
+                    for sub_index, event in enumerate(
+                        self.parse_record(record, path=path, session_id=session_id)
+                    ):
+                        if event.line_number is None:
+                            event.line_number = lineno
+                        if event.line_sub_index is None:
+                            event.line_sub_index = sub_index
+                        yield event
+                except Exception as exc:  # noqa: BLE001 - adapters must never crash the pipeline
+                    yield NormalizedEvent(
+                        vendor=self.vendor,
+                        event_type=EventType.UNKNOWN,
+                        session_id=session_id,
+                        source_file=str(path),
+                        raw_type="_adapter_error",
+                        line_number=lineno,
+                        extra={"error": str(exc)},
+                        raw=record if isinstance(record, dict) else {"value": record},
+                    )
+        finally:
+            fh.close()
+
+    @abc.abstractmethod
+    def parse_record(self, record: dict, *, path: Path, session_id: str) -> Iterator[NormalizedEvent]:
+        """Yield zero or more NormalizedEvent for a single decoded JSON line."""

agent_session_otel/adapters/claude_code.py

@@ -0,0 +1,248 @@
+"""Adapter for Claude Code session transcripts.
+
+Claude Code writes one append-only JSONL file per session under
+``~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`` (subagent
+transcripts are named ``agent-<id>.jsonl``). Each line has a ``type``
+discriminator (``summary``, ``user``, ``assistant``, ``system``,
+``file-history-snapshot``, ...). This module is intentionally defensive:
+the format is not officially specified and has evolved over time, so
+every lookup is best-effort and anything we don't recognize is preserved
+via ``EventType.UNKNOWN`` rather than dropped.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterator, List
+
+from .. import discovery
+from ..schema import EventType, NormalizedEvent, normalize_usage
+from .base import SessionAdapter
+
+
+class ClaudeCodeAdapter(SessionAdapter):
+    vendor = "claude_code"
+
+    def discover(self, roots=None) -> List[Path]:
+        return discovery.discover_claude_code_files(roots)
+
+    def parse_record(self, record: dict, *, path: Path, session_id: str) -> Iterator[NormalizedEvent]:
+        if not isinstance(record, dict):
+            yield NormalizedEvent(
+                vendor=self.vendor,
+                event_type=EventType.UNKNOWN,
+                session_id=session_id,
+                source_file=str(path),
+                raw_type="_non_object_record",
+                raw={"value": record},
+            )
+            return
+
+        session_id = record.get("sessionId") or session_id
+        rtype = record.get("type")
+        common = dict(
+            vendor=self.vendor,
+            session_id=session_id,
+            source_file=str(path),
+            timestamp=record.get("timestamp"),
+            event_id=record.get("uuid"),
+            parent_id=record.get("parentUuid"),
+            cwd=record.get("cwd"),
+            raw_type=rtype,
+            extra={
+                k: record.get(k)
+                for k in ("gitBranch", "version", "isSidechain", "userType")
+                if record.get(k) is not None
+            },
+        )
+
+        if rtype == "summary":
+            yield NormalizedEvent(
+                event_type=EventType.SESSION,
+                content=record.get("summary"),
+                extra={**common["extra"], "kind": "summary", "leaf_uuid": record.get("leafUuid")},
+                raw=record,
+                **{k: v for k, v in common.items() if k != "extra"},
+            )
+            return
+
+        if rtype == "file-history-snapshot":
+            yield NormalizedEvent(
+                event_type=EventType.SESSION,
+                extra={**common["extra"], "kind": "file_history_snapshot"},
+                raw=record,
+                **{k: v for k, v in common.items() if k != "extra"},
+            )
+            return
+
+        if rtype == "system":
+            level = record.get("level")
+            if level == "error":
+                yield NormalizedEvent(
+                    event_type=EventType.ERROR,
+                    error_message=record.get("content"),
+                    extra={**common["extra"], "subtype": record.get("subtype")},
+                    raw=record,
+                    **{k: v for k, v in common.items() if k != "extra"},
+                )
+            else:
+                yield NormalizedEvent(
+                    event_type=EventType.SESSION,
+                    content=record.get("content") if isinstance(record.get("content"), str) else None,
+                    extra={**common["extra"], "kind": "system", "subtype": record.get("subtype"), "level": level},
+                    raw=record,
+                    **{k: v for k, v in common.items() if k != "extra"},
+                )
+            return
+
+        if rtype == "user":
+            yield from self._parse_user(record, common)
+            return
+
+        if rtype == "assistant":
+            yield from self._parse_assistant(record, common)
+            return
+
+        # Unrecognized top-level type: preserve, don't drop.
+        yield NormalizedEvent(
+            event_type=EventType.UNKNOWN,
+            raw=record,
+            **{k: v for k, v in common.items() if k != "extra"},
+            extra=common["extra"],
+        )
+
+    def _parse_user(self, record: dict, common: dict) -> Iterator[NormalizedEvent]:
+        message = record.get("message") or {}
+        content = message.get("content")
+        role = message.get("role", "user")
+        tool_use_result = record.get("toolUseResult")
+
+        if isinstance(content, str):
+            yield NormalizedEvent(
+                event_type=EventType.TURN,
+                role=role,
+                content=content,
+                raw=record,
+                **{k: v for k, v in common.items() if k != "extra"},
+                extra=common["extra"],
+            )
+            return
+
+        if isinstance(content, list):
+            emitted = False
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "tool_result":
+                    emitted = True
+                    output = block.get("content")
+                    yield NormalizedEvent(
+                        event_type=EventType.TOOL,
+                        tool_phase="result",
+                        tool_call_id=block.get("tool_use_id"),
+                        tool_output=output if output is not None else tool_use_result,
+                        raw=record,
+                        **{k: v for k, v in common.items() if k != "extra"},
+                        extra={**common["extra"], "is_error": block.get("is_error", False)},
+                    )
+                elif btype == "text" and isinstance(block.get("text"), str):
+                    emitted = True
+                    yield NormalizedEvent(
+                        event_type=EventType.TURN,
+                        role=role,
+                        content=block["text"],
+                        raw=record,
+                        **{k: v for k, v in common.items() if k != "extra"},
+                        extra=common["extra"],
+                    )
+            if not emitted:
+                yield NormalizedEvent(
+                    event_type=EventType.TURN,
+                    role=role,
+                    raw=record,
+                    **{k: v for k, v in common.items() if k != "extra"},
+                    extra=common["extra"],
+                )
+            return
+
+        # No recognizable message content at all -- still preserve the line.
+        yield NormalizedEvent(
+            event_type=EventType.TURN,
+            role=role,
+            raw=record,
+            **{k: v for k, v in common.items() if k != "extra"},
+            extra=common["extra"],
+        )
+
+    def _parse_assistant(self, record: dict, common: dict) -> Iterator[NormalizedEvent]:
+        message = record.get("message") or {}
+        role = message.get("role", "assistant")
+        model = message.get("model")
+        content = message.get("content")
+        stop_reason = message.get("stop_reason")
+        extra = {**common["extra"], "stop_reason": stop_reason}
+
+        if isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "text" and isinstance(block.get("text"), str):
+                    yield NormalizedEvent(
+                        event_type=EventType.TURN,
+                        role=role,
+                        model=model,
+                        content=block["text"],
+                        raw=record,
+                        **{k: v for k, v in common.items() if k != "extra"},
+                        extra=extra,
+                    )
+                elif btype == "thinking" and isinstance(block.get("thinking"), str):
+                    yield NormalizedEvent(
+                        event_type=EventType.TURN,
+                        role=role,
+                        model=model,
+                        content=block["thinking"],
+                        raw=record,
+                        **{k: v for k, v in common.items() if k != "extra"},
+                        extra={**extra, "phase": "thinking"},
+                    )
+                elif btype == "tool_use":
+                    yield NormalizedEvent(
+                        event_type=EventType.TOOL,
+                        tool_phase="call",
+                        tool_name=block.get("name"),
+                        tool_call_id=block.get("id"),
+                        tool_input=block.get("input"),
+                        model=model,
+                        raw=record,
+                        **{k: v for k, v in common.items() if k != "extra"},
+                        extra=extra,
+                    )
+        elif isinstance(content, str):
+            yield NormalizedEvent(
+                event_type=EventType.TURN,
+                role=role,
+                model=model,
+                content=content,
+                raw=record,
+                **{k: v for k, v in common.items() if k != "extra"},
+                extra=extra,
+            )
+
+        usage = message.get("usage")
+        if isinstance(usage, dict):
+            yield NormalizedEvent(
+                event_type=EventType.USAGE,
+                model=model,
+                usage=normalize_usage(
+                    input_tokens=usage.get("input_tokens"),
+                    output_tokens=usage.get("output_tokens"),
+                    cache_read_input_tokens=usage.get("cache_read_input_tokens"),
+                    cache_creation_input_tokens=usage.get("cache_creation_input_tokens"),
+                ),
+                raw=record,
+                **{k: v for k, v in common.items() if k != "extra"},
+                extra={**extra, "service_tier": usage.get("service_tier")},
+            )