Expand description
Exec-style event view over app-server notifications (issue #213).
Downstream renderers (agent-portal’s codex-session-lib was the filing
consumer) want a stable, serializable event stream in the shape of the
CLI’s codex exec JSONL — without hand-rolling a synthetic struct per
notification and re-serializing typed items back into JSON.
The serialized contract (settled with that consumer before adoption,
and matching real exec JSONL, which is FLAT — thread.started carries
thread_id top-level, turn.completed lifts turn_id/status/
duration_ms):
- Lifecycle events use dotted exec tags (
thread.started,turn.completed,item.started, …) with snake_case event-level fields lifted flat, plus the full typed payload riding along (thread:/turn:) for consumers that want more than the flat keys. - Everything else serializes as a forwarded notification:
{"type": "<slash-form method>", "params": <inner payload>}— e.g.turn/diff/updated,item/agentMessage/delta. The dot/slash split is load-bearing: dots are thread events, slashes are verbatim app-server notifications. - Item payloads embed the typed
ThreadItem, which serializes in the app-server’s camelCase item shape ("commandExecution", not exec’s"command_execution"). - Turn errors arrive as
turn.failed, never as a bareerrortag — that tag stays free for host-level errors (the portal claims it). item.updatedis absent by construction: the exec format has the tag, but app-server 0.147 has no item-update notification to map from (item/fileChange/patchUpdatedis the closest, and rides the slash passthrough). A consumer synthesizingitem.updatedlocally keeps doing so.
Enums§
- Exec
Event - One renderable event. See the module docs for the serialized contract.