codex - 💡(How to fix) Fix Document session JSONL schema stability for external integrations [2 comments, 3 participants]

What feature would you like to see?

A docs page that defines which session JSONL fields/events are stable for external tooling and which are internal/subject to change.

Problem

External integrations (dashboards, wrappers, review surfaces, CI helpers) consume Codex session JSONL, but there is no explicit stability contract. This forces parsers to depend on implementation details and breaks across updates.

Proposal

Add a docs section (for example docs/session-jsonl.md) that includes:

1. Event envelope shape and required top-level fields.
2. Event type catalog currently emitted in session JSONL.
3. Stability level for each field:
   • stable for external use
   • experimental
   • internal
4. Versioning guidance:
   • how additions/removals are communicated
   • how external parsers should handle unknown fields/events
5. One or two realistic examples from interactive and codex exec runs.

Why this helps

• Lowers friction for community integrations without requiring new runtime features.
• Reduces duplicate "parser broke" issues.
• Creates a clear foundation for future lifecycle APIs/events.

Acceptance criteria

1. Docs explicitly define a stability contract for session JSONL fields.
2. Docs list at least one canonical sample per run mode (interactive and exec).
3. Docs include forward-compat parser guidance (ignore unknown fields, branch by version when present).
4. Changelog/release notes point to this contract when format-affecting changes ship.

Scope note

This request is docs-first and additive. It does not require changing current JSONL emission behavior.