Skip to main content

Module events

Module events 

Source
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 bare error tag — that tag stays free for host-level errors (the portal claims it).
  • item.updated is absent by construction: the exec format has the tag, but app-server 0.147 has no item-update notification to map from (item/fileChange/patchUpdated is the closest, and rides the slash passthrough). A consumer synthesizing item.updated locally keeps doing so.

Enums§

ExecEvent
One renderable event. See the module docs for the serialized contract.