Document session JSONL schema stability for external integrations

[sanyathoque]

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.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Expose stable run/review lifecycle metadata for Codex tasks #20943

Powered by Codex Action

[etraut-openai]

I don't think we're prepared to treat this as a documented, stable contract at this time. We will endeavor not to make unnecessary changes, but you should expect to see this schema to continue to evolve.

We are treating the app server interface as a durable, stable, and fully-documented API. I don't know if that interface works for your use case, but if you're concerned about long-term interface stability, that might be a better option for you.

[sanyathoque]

Thanks for the clarification — this is helpful direction.

I’ll treat session JSONL as internal/evolving and move integration proposals toward the app-server interface when long-term stability is required.

If useful, I can open or draft a docs-only follow-up that explicitly guides external integrators to prefer app-server over session JSONL for stable client integrations.