Canonical lifecycle event types for run events

Start with src/Runtime/class-wp-agent-run-control.php and its normalize_event() helper, then compare the event and status definitions in src/Channels/register-agents-chat-run-control-abilities.php. Trace the workflow and runtime-package event entry points named in the issue. Done means the canonical and namespaced types, terminal-status pairings, schema validation, round-trip behavior, and documentation are covered by tests without changing adapters.

Problem

Run events have an open-ended type. WP_Agent_Run_Control::normalize_event() copies whatever string the adapter emits, and the output schema declares type as a plain string. Run status right next to it is a closed enum.

So a client can reason about the state of a run, but not about anything that happened inside it. Every runtime invents its own event names, which means a chat UI, a channel, or a relay written against one runtime cannot read another runtime's events. That portability is the reason the run-event contract exists.

The same normalizer backs workflow, task, and runtime-package run events, so the gap is repo-wide, not chat-only.

Evidence

• src/Runtime/class-wp-agent-run-control.php — normalize_event() passes type through string_value() with no validation.
• src/Channels/register-agents-chat-run-control-abilities.php — agents_chat_run_events_output_schema() declares 'type' => array( 'type' => 'string' ), while status in the same schema carries 'enum' => WP_Agent_Chat_Run_Control::statuses().
• agents/list-workflow-run-events and agents/list-runtime-package-run-events normalize through the same helper.

Required contract

• Name a canonical set of lifecycle event types. At minimum: run queued, run started, assistant output text delta, assistant output text done, tool call requested, tool call completed, run blocked on a runtime tool result, run blocked on an approval, run completed, run failed, run cancelled.
• Derive the names from the existing run status enum so status and events stay one vocabulary instead of two.
• Keep adapter-specific types allowed. Reserve the canonical prefix, and document that anything else must be namespaced, so a client can ignore an unknown type safely.
• Document which canonical event each terminal status is expected to be paired with.
• Contracts and docs only. Adapters that emit no events today keep working unchanged.

Tests

• Every canonical type round-trips through normalize_event() and validates against the events output schema.
• A namespaced adapter-specific type round-trips unchanged.
• A run that ends in each terminal status emits the matching canonical terminal event.
• Workflow and runtime-package run events accept the same canonical types.