Automattic / Automattic/agents-api
Canonical lifecycle event types for run events
- Dominant language
- PHP
- Stars
- 33
- Forks
- 8
- Avg merge
- 1h 39m
- Merged PRs (30d)
- 30
Description
## 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.
Contributor guide
No contributing guide indexed for this repository
Research direction
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.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100