agent-session-otel 0.2.0__tar.gz

agent_session_otel-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest --cov=agent_session_otel --cov-report=term-missing
+
+      - name: CLI smoke test
+        run: |
+          agent-session-otel doctor
+          agent-session-otel inspect --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+          agent-session-otel export --format json --output trace.json --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+          python -c "import json; json.load(open('trace.json'))"
+
+  # A minimal representative check on macOS/Windows -- one Python version
+  # each, not the full matrix, so CI stays fast while still catching
+  # platform-specific path/permissions bugs that Linux-only CI would miss.
+  cross-platform:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package with dev extras
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: pytest
+      - name: CLI smoke test
+        run: |
+          agent-session-otel doctor
+          agent-session-otel inspect --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+          agent-session-otel export --format json --output trace.json --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+          python -c "import json; json.load(open('trace.json'))"
+
+  # Base install (no extras) must work with zero third-party dependencies
+  # for `inspect`/`doctor`, and fail cleanly (not with a traceback) for
+  # `export` -- this is a packaging invariant, not just a unit-test one.
+  base-install-no-extras:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install .
+      - run: agent-session-otel --help
+      - run: agent-session-otel doctor
+      - run: agent-session-otel inspect --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+      - name: export without the otel extra fails cleanly, not with a traceback
+        run: |
+          set +e
+          agent-session-otel export --format json --output trace.json \
+            --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex 2> err.txt
+          code=$?
+          cat err.txt
+          if [ "$code" -ne 1 ] || grep -q "Traceback" err.txt; then
+            echo "expected a clean exit-1 error, got exit $code with a traceback"
+            exit 1
+          fi
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Check package metadata
+        run: |
+          python -m pip install twine
+          twine check dist/*
+      - name: Install the built wheel into a clean venv and smoke-test it
+        run: |
+          python -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/pip install "$(ls dist/*.whl)[otel]"
+          /tmp/wheel-venv/bin/agent-session-otel --help
+          /tmp/wheel-venv/bin/agent-session-otel export --format json --output /tmp/wheel-trace.json \
+            --claude-code-root tests/fixtures/claude_code --codex-root tests/fixtures/codex
+          python -c "import json; json.load(open('/tmp/wheel-trace.json'))"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

agent_session_otel-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing (OIDC), no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_session_otel-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg
+.mypy_cache/

agent_session_otel-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.2.0
+
+Production-hardening pass ahead of the first public release.
+
+- **Privacy:** local file paths (`cwd`, session source file) are now
+  redacted by default instead of passed through; path-shaped dict keys
+  (e.g. Claude Code's file-backup tracking) are redacted, not just
+  values; a secret-pattern scrubber (API keys, bearer tokens, private
+  key blocks, URL-embedded credentials, ...) now runs unconditionally,
+  including under `--include-content`.
+- **Idempotency:** trace/span ids are now derived deterministically from
+  `(vendor, session id, event position)` instead of randomly generated,
+  so re-running `export` against unchanged sessions reproduces the same
+  ids, and exact duplicate events within one run are detected and
+  exported once (`asot.duplicate_events_skipped`).
+- **OTel semantics:** migrated from the retired `gen_ai.system` attribute
+  to `gen_ai.provider.name`; added `gen_ai.agent.name`,
+  `gen_ai.operation.name`, and the opt-in `gen_ai.input.messages`/
+  `gen_ai.output.messages` shape; renamed span types that aren't actually
+  part of the GenAI spec (`gen_ai.usage` → `asot.usage_snapshot`,
+  `gen_ai.error` → `asot.error_event`, `gen_ai.session_event` →
+  `asot.session_event`) so only real spec attributes/spans use `gen_ai.*`;
+  matched tool call/result pairs now merge into one `execute_tool` span
+  with a real duration instead of two disconnected zero-duration spans.
+- **Resilience:** session files are streamed line-by-line instead of
+  loaded into memory (tested against a 200k-event/41MB synthetic session);
+  a file that can't be opened at all becomes one `unknown` event instead
+  of crashing the whole scan; discovery no longer assumes `$HOME`
+  resolves.
+- **CLI:** unexpected errors (bad output path, malformed OTLP endpoint,
+  Ctrl+C) now produce a one-line message and a sane exit code instead of
+  a raw Python traceback; `--verbose` shows the full traceback when you
+  want it.
+- **Packaging:** `opentelemetry-api`/`opentelemetry-sdk` moved from hard
+  dependencies to the new `otel` extra -- `inspect`/`doctor` now install
+  with zero third-party dependencies. `export` needs `[otel]`;
+  `export --format otlp` needs `[otlp]`.
+- **Schema:** added an explicit `SCHEMA_VERSION` and documented the
+  canonical-schema invariants (vendor concepts never become new
+  top-level fields).
+
+## 0.1.0
+
+Initial release: Claude Code and Codex CLI adapters, canonical event
+schema, redaction, local-JSON and OTLP export, `inspect`/`export`/`doctor`
+CLI.

agent_session_otel-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Bug reports and PRs are welcome.
+
+## Setup
+
+```bash
+git clone https://github.com/ryan-wolbeck/agent-session-otel.git
+cd agent-session-otel
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+## Adding or updating adapter behavior
+
+Claude Code and Codex's JSONL formats are undocumented and change
+between releases. If you're adding support for a new vendor event shape:
+
+1. Add a fixture line to `tests/fixtures/claude_code/` or
+   `tests/fixtures/codex/` (or a synthetic record in
+   `tests/test_hostile_inputs.py` if it's an edge case rather than a
+   realistic full session).
+2. Map it to one of the five canonical event types in
+   `agent_session_otel/schema.py` (`session`/`turn`/`tool`/`usage`/`error`)
+   -- or, if it genuinely doesn't fit, leave it as `unknown`. Don't add a
+   new top-level schema field to accommodate a vendor-specific concept;
+   see the invariants documented at the top of `schema.py`.
+3. Never put free-text content in `extra` -- it bypasses redaction.
+   Content belongs in `content`/`tool_input`/`tool_output`/`error_message`/`raw`.
+4. If it's genuinely new information, run it past `otel_export.py`'s
+   module docstring before inventing a `gen_ai.*`-looking attribute name.
+   Check the [GenAI semantic conventions registry](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/gen-ai/registry.yaml)
+   first; if it's not there, use the `asot.*` namespace instead.
+
+## Privacy-sensitive changes
+
+Anything touching redaction (`redaction.py`), what gets attached to
+exported spans (`otel_export.py`), or what a normalized event exposes
+(`schema.py`) should come with a test proving the sensitive value does
+*not* appear in default (non-`--include-content`) output. See
+`tests/test_redaction.py` and the redaction-specific tests in
+`tests/test_export.py` for the pattern.
+
+## Running the CLI against your own real sessions
+
+`agent-session-otel doctor` and `agent-session-otel inspect` are safe to
+run against your real `~/.claude/projects` / `~/.codex/sessions` --
+discovery is read-only and inspection is redacted by default. Don't paste
+`--include-content` output into an issue or PR.

agent_session_otel-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wolbeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_session_otel-0.2.0/PKG-INFO

@@ -0,0 +1,332 @@
+Metadata-Version: 2.5
+Name: agent-session-otel
+Version: 0.2.0
+Summary: Discover local Claude Code / Codex session logs and export them as OpenTelemetry GenAI-compatible traces.
+Project-URL: Homepage, https://github.com/ryan-wolbeck/agent-session-otel
+Project-URL: Issues, https://github.com/ryan-wolbeck/agent-session-otel/issues
+Author: Ryan Wolbeck
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,genai,observability,opentelemetry,otel,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: opentelemetry-api>=1.24; extra == 'dev'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otlp'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'otlp'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otlp'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.1; extra == 'test'
+Requires-Dist: pytest>=7.4; extra == 'test'
+Description-Content-Type: text/markdown
+
+# agent-session-otel
+
+Turn the session logs [Claude Code](https://claude.com/claude-code) and
+[Codex CLI](https://github.com/openai/codex) already write to your local
+disk into [OpenTelemetry](https://opentelemetry.io/) traces, using the
+(still-evolving) [GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai).
+
+```
+Claude Code session logs ──→ ClaudeCodeAdapter ──┐
+                                                  ├──→ canonical events ──→ OTel spans ──→ JSON file / OTLP
+Codex CLI session logs   ──→ CodexAdapter      ──┘
+```
+
+Both vendors' JSONL formats are undocumented, unstable, and evolve
+between releases. This tool treats them as exactly that: two
+disposable *adapters* that normalize into one small, stable, vendor-neutral
+schema (`session` / `turn` / `tool` / `usage` / `error`, plus an `unknown`
+catch-all). Nothing outside the two adapter modules knows Claude Code or
+Codex's field names. When a vendor changes its format -- which will
+happen -- unrecognized events are preserved (not dropped), and adding a
+third vendor doesn't touch the canonical schema or the OTel export code.
+
+## Why not native telemetry?
+
+Neither tool exports OpenTelemetry today. Their session logs are replay
+transcripts for their own resume/UI features, not telemetry -- different
+shape, different guarantees, and no cross-vendor consistency. This tool
+reconstructs *after the fact* what a trace of that session would have
+looked like, so you can point your existing observability stack (or a
+local JSON file, no stack required) at your actual coding-agent usage.
+It does not run a web UI, does not run a database, and does not talk to
+any vendor API -- it reads files already on disk and writes OTel data.
+
+## What leaves your machine?
+
+**By default: no prompt text, no file contents, no tool arguments/output,
+no local file paths.** Every content-bearing field is replaced with a
+`<redacted:len=N:sha256=...>` placeholder, and local paths (which for
+Claude Code literally encode your project's absolute path into a
+directory name) are collapsed to just a basename. Structural metadata --
+event types, timestamps, token counts, tool *names* (not arguments),
+model names -- passes through, since that's what makes the trace useful
+without being sensitive.
+
+Passing `--include-content` opts into carrying real prompt/tool/file
+content through end to end -- do this only when exporting to a
+destination you trust with that content. Even then, a secret-pattern
+scrubber (API keys, bearer tokens, private key blocks, credentials
+embedded in URLs, ...) still runs; `--include-content` opts into your
+own prompts and file content, not into leaking a credential that happens
+to appear in them.
+
+See [Privacy defaults](#privacy-defaults) below for the full detail.
+
+## Install
+
+```bash
+# `inspect` and `doctor` work with zero third-party dependencies.
+pip install agent-session-otel
+
+# `export` (either format) needs the OTel SDK:
+pip install "agent-session-otel[otel]"
+
+# `export --format otlp` additionally needs the OTLP/HTTP exporter:
+pip install "agent-session-otel[otlp]"
+```
+
+## Quick start
+
+```bash
+# Sanity-check your environment and see what sessions are discoverable.
+agent-session-otel doctor
+
+# Summarize local sessions (Claude Code + Codex, redacted).
+agent-session-otel inspect
+```
+```
+claude_code  cc-a1b2c3d4
+  file:        <redacted-path>/cc-a1b2c3d4.jsonl
+  time range:  2026-08-01T10:00:00.000Z  ->  2026-08-01T10:14:22.000Z
+  events:      session=2, turn=11, tool=6, usage=6, unknown=3
+  tokens:      input=18300 output=2140
+```
+```bash
+# Dump normalized events as JSON lines, content still redacted.
+agent-session-otel inspect --json --vendor claude-code
+
+# Export everything found as a local OTel JSON trace document.
+agent-session-otel export --format json --output trace.json
+
+# Export to a running OTel collector, including real content (opt-in).
+agent-session-otel export --format otlp \
+  --endpoint http://localhost:4318/v1/traces \
+  --include-content
+```
+
+## Commands
+
+### `agent-session-otel inspect`
+
+Discovers session files and prints a human-readable summary per session
+(event counts, token totals, time range). `--json` prints one normalized
+event per line instead (the canonical schema -- see below).
+
+### `agent-session-otel export`
+
+Normalizes discovered sessions and exports them as an OpenTelemetry
+trace: one root `invoke_agent <agent>` span per session, with one child
+span per normalized event -- `chat` for turns, `execute_tool` for tool
+calls (merged with their matching result into one span, when both are
+present, so span duration reflects the tool's actual runtime), and
+`asot.*`-namespaced spans for usage snapshots, diagnostic/session events,
+errors, and anything preserved-but-unrecognized.
+
+`--format json` needs no collector -- it writes a self-contained JSON
+document of the spans. `--format otlp` requires the `otlp` extra and a
+reachable OTLP/HTTP traces endpoint.
+
+Re-running `export` against the same, unmodified session files produces
+the same trace/span ids every time (derived from the vendor's session id
+and each event's position in the file, not randomly generated), so a
+backend that dedupes on (trace_id, span_id) recognizes a repeated import
+instead of double-counting it. See [Idempotency](#idempotency-re-running-export).
+
+### `agent-session-otel doctor`
+
+Checks the Python version, whether the OTel SDK / OTLP exporter extras
+are installed, and does an end-to-end discovery + parse smoke test
+against your real session directories. Exits non-zero only on fatal
+problems -- a missing session directory, or the OTel extras not being
+installed, are warnings, not errors, since `inspect`/`doctor` don't need
+them.
+
+## Options common to `inspect` and `export`
+
+| Flag | Description |
+| --- | --- |
+| `--vendor {claude-code,codex,all}` | Limit to one vendor. Default: `all`. |
+| `--claude-code-root PATH` | Override the Claude Code session root (repeatable). Default: `~/.claude/projects`. |
+| `--codex-root PATH` | Override the Codex session root (repeatable). Default: `~/.codex/sessions`. |
+| `--session-id ID` | Limit to session(s) whose filename matches `ID` (repeatable). |
+| `--include-content` | Opt-in: carry real prompt/tool/error text through instead of redacting it. |
+| `--verbose` | Show a full traceback (instead of a one-line message) if something unexpected fails. |
+
+Session roots can also be set via `AGENT_SESSION_OTEL_CLAUDE_CODE_HOME` and
+`AGENT_SESSION_OTEL_CODEX_HOME`. Neither Claude Code, Codex, nor the
+directories they write to are ever installed or required -- `doctor` and
+`inspect` simply report zero sessions found for whichever vendor isn't
+present on your machine, which is not an error.
+
+## Canonical schema
+
+Every adapter normalizes into `agent_session_otel.schema.NormalizedEvent`:
+one of `session` / `turn` / `tool` / `usage` / `error` / `unknown`, plus
+role, model, content, tool name/id/input/output, token usage, an
+`extra` dict for small structural vendor-specific tags, and `raw` holding
+the original vendor record for lossless preservation. `SCHEMA_VERSION`
+(currently `1`, present on every exported/inspected event) bumps whenever
+a field's meaning changes, so downstream consumers can detect a schema
+they don't understand.
+
+**Invariant:** vendor-specific concepts never become new top-level
+schema fields. If a Claude Code or Codex event doesn't map onto one of
+the five categories, it becomes `unknown` with the original record
+preserved -- it is not dropped, and the schema does not grow a
+Claude-Code-shaped or Codex-shaped field to accommodate it.
+
+## OpenTelemetry mapping
+
+Span and attribute names follow the
+[GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
+wherever a convention genuinely exists for the concept being represented
+(`gen_ai.provider.name`, `gen_ai.agent.name`, `gen_ai.operation.name`,
+`gen_ai.conversation.id`, `gen_ai.usage.*`, `gen_ai.tool.*`,
+`gen_ai.input.messages` / `gen_ai.output.messages`). **The entire GenAI
+semconv is `development`-stability as of this writing** -- expect
+upstream attribute renames (this project already migrated once, from the
+now-retired `gen_ai.system` to `gen_ai.provider.name`).
+
+Anything this tool needs that the spec doesn't define is namespaced
+under `asot.*` rather than given an official-looking `gen_ai.*` name:
+`asot.usage_snapshot` and `asot.error_event` (standalone spans for
+events that don't cleanly attach to one chat/tool span), `asot.session_event`
+(session-level metadata), `asot.unknown_event` (preserved-but-unmodeled
+vendor events, full redacted payload in `asot.raw`), and
+`asot.duplicate_events_skipped` (see Idempotency).
+
+**Reconstructed vs. live telemetry:** these are historical traces built
+from a static log file, not live instrumentation. Span kind is always
+`INTERNAL`. A tool span's duration is the gap between its call and result
+*as logged*, not a live-measured duration. Timestamps the vendor didn't
+record are synthesized (nudged forward by 1μs from the prior event) purely
+so spans stay orderable -- they are not real wall-clock times. None of
+this is hidden: it's documented in `otel_export.py`'s module docstring,
+which is worth reading before you alert on these traces as if they were
+live data.
+
+## Idempotency (re-running `export`)
+
+Trace and span ids are derived deterministically from `(vendor, session
+id, event position in file)` -- not randomly generated. Re-running
+`export` against unchanged session files reliably reproduces the same
+ids, and within a single run, an exact repeat of the same event (e.g. the
+same file reachable from two overlapping `--claude-code-root` values)
+is detected and exported once, with the count of skipped repeats on the
+session's root span (`asot.duplicate_events_skipped`).
+
+This is a best-effort identity scheme, not a cryptographic guarantee: a
+session id collision across genuinely different content, or a file
+edited/reordered in place rather than purely appended to, would not be
+caught. It is keyed on the vendor's own session id plus each event's
+line position, not on the local absolute file path (which isn't part of
+a session's identity, and which redaction hides by default anyway).
+
+## Privacy defaults
+
+By default, every leaf string value that could contain user or model
+content -- message text, tool arguments/output, error messages, local
+file paths (including dict *keys* that are themselves paths, e.g. Claude
+Code's file-backup tracking), and the equivalent fields inside preserved
+raw vendor payloads -- is replaced with `<redacted:len=N:sha256=...>` (or,
+for paths, collapsed to `<redacted-path>/basename`). Structural fields
+(ids, timestamps, roles, event types, tool *names*, token counts, model
+names) are never redacted.
+
+`--include-content` disables that wholesale redaction and carries real
+content through -- but a separate secret-pattern scrubber (AWS keys,
+GitHub/Slack tokens, JWTs, bearer tokens, private key blocks, URL-embedded
+credentials, common `key=`/`token=`/`password=` assignments) always
+runs, opt-in or not, replacing matches with `<redacted-secret:label>`.
+It is a best-effort net, not a guarantee -- it cannot catch every secret
+shape, especially ones split across multiple tokens or non-standard
+formats. Treat `--include-content` output as sensitive regardless.
+
+## Filesystem safety
+
+Discovery only ever reads `*.jsonl` files under the configured roots --
+it never writes to, modifies, or deletes anything Claude Code or Codex
+manages. A permission-denied subdirectory, a non-directory root, a
+symlink loop, or an unresolvable `$HOME` are all handled gracefully
+(skipped with a warning, not a crash); a single unreadable or malformed
+*file* becomes one `unknown` event rather than aborting the whole scan.
+
+## Supported versions and forward compatibility
+
+There is no official spec for either vendor's session JSONL format, and
+both have changed shape across releases (this project's Codex adapter was
+written against a schema noticeably more complex than what was documented
+in older community write-ups). Every field lookup in both adapters is
+defensive (`.get()` with fallbacks, never an assumed key), and anything
+that doesn't match a known shape -- a new top-level record type, a new
+tool-call variant, a field that's now `null` where it used to be a string
+-- becomes an `unknown` normalized event carrying the original record,
+rather than raising or silently vanishing. On real Claude Code and Codex
+history on the machine this was developed on, a meaningful fraction of
+events fall into `unknown` today; that number going up over time as
+vendors ship changes is expected, not a bug, and `agent-session-otel
+doctor` reports it directly so you can see your own coverage.
+
+## Development
+
+```bash
+git clone https://github.com/ryan-wolbeck/agent-session-otel.git
+cd agent-session-otel
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+Fixture-based tests live under `tests/fixtures/`. `tests/test_hostile_inputs.py`
+specifically targets malformed/truncated/empty/oversized/non-UTF-8 input;
+`tests/test_export.py` covers OTel semantics, deterministic ids, and
+redaction; `tests/test_redaction.py` and the secret-scrubbing tests in
+`test_export.py` are the ones to extend first if you're touching privacy
+behavior. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Scope
+
+This project is a CLI that reads local JSONL files and writes OTel
+traces. It does not run a web UI, does not run a database, does not
+require authentication, and does not talk to any vendor API. It's meant
+to sit alongside your existing observability stack, not replace it.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for how to report a vulnerability.
+
+## License
+
+MIT