Clarify event sink contract: on_event callable vs documented filter

[lezama]

Question

AgentConversationLoop::run() already accepts an on_event callable that receives lifecycle events (turn_started, tool_call, tool_result, budget_exceeded, completed, failed). For a single consumer this is enough.

The unanswered question: when multiple independent observers want to attach to the same loop — telemetry, audit log, async replay queue, dev-mode console logger — does the substrate ship its own multiplexer, or is the consumer expected to compose one above on_event?

This isn't urgent, but it's the kind of decision that's painful to revisit later because every adopter writes their own multiplexer with subtly different ordering and error semantics.

Two shapes worth deciding between

Option A — on_event is canonical, multiplexing is the consumer's problem

Document the existing callable as the only extension point. Consumers that need multiple sinks compose their own:

$on_event = function ( string $event, array $payload ) use ( $sinks ): void {
    foreach ( $sinks as $sink ) {
        try { $sink( $event, $payload ); } catch ( \Throwable $e ) { /* log, continue */ }
    }
};

Pros: zero new substrate surface. Maximum flexibility — consumers control ordering, error handling, async dispatch.
Cons: every consumer reinvents the multiplexer with subtly different error semantics. Two plugins both wanting to observe the same loop have no documented way to compose without one wrapping the other.

Option B — Add documented agents_api_loop_event action

Substrate emits a WordPress action alongside the on_event callable:

do_action( 'agents_api_loop_event', $event, $payload, $loop_context );

Independent observers attach with add_action(). Standard WP composition rules apply.

Pros: idiomatic for WP host plugins. Composition is free. Independent observers can attach without coordinating.
Cons: two extension points (callable + action) to document and reason about. Action-based observers can't easily mutate the event payload — needs a clear stance on whether observers are read-only.

Option C — Replace the callable with the action

Cut the callable, route everything through the action. Cleanest surface but a public-API break for any caller already using on_event.

Resolution would inform

• Whether a future PR introduces agents_api_loop_event (or similarly named) and what its lifecycle is relative to the on_event callable.
• Whether observers are guaranteed read-only (action) or can transform the payload (filter).
• Whether sink errors halt the loop (transparent throw) or are swallowed (per-sink try/catch in the multiplexer).
• Whether async sinks are in scope (the substrate stays sync; consumers queue if they need async).

Recommendation (weak)

Option B with action semantics: keep the existing on_event callable for tightly-coupled callers (the request adapter wiring), and add agents_api_loop_event as the canonical extension point for cross-cutting observers. Sink errors are caught and logged but do not halt the loop — observability must never break the agent's actual job.

Open to the other shapes; filing this as a decision issue rather than a build issue.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Auditing AgentConversationLoop for existing extension points and drafting the decision options.

[lezama]

Reference precedent: typed lifecycle objects

A second extraction effort outside Data Machine has the typed-event variant of Option B already shipped — five concrete classes that the runtime emits as it progresses:

• WP_Agent_Stream_Delta — incremental token / partial output
• WP_Agent_Progress — progress updates emitted by long-running tools or multi-turn loops
• WP_Agent_Queued — work was deferred (async path)
• WP_Agent_Input_Required — runtime needs a user response before continuing (pending action / approval)
• WP_Agent_Final_Result — terminal outcome of the run

This is a working precedent for Option B with typed events rather than (string $event, array $payload). Concrete advantages observed there:

1. Discoverability — IDE / static analysis surfaces the available events, vs. a free string vocabulary.
2. Schema enforcement — Stream_Delta carries token + index; Progress carries percentage + label; Final_Result carries the assembled result. The shape is a class invariant, not a convention.
3. Composition with the loop — the lifecycle objects are reusable in HTTP streaming responses (SSE), CLI progress bars, and async polling endpoints with no payload mapping in between.
4. Pending-action integration — Input_Required ties cleanly into the PendingAction substrate (Promote durable pending action approval contracts #71). The typed event is the natural way to emit "I need your approval" from the loop without the orchestrator inventing its own event vocabulary.

Proposed merge of the two extraction efforts

If the substrate adopts typed events, the path is:

1. Lift the five lifecycle classes into src/Runtime/Events/ (or similar).
2. AgentConversationLoop::run() keeps the existing on_event callable but documents it as receiving instances of an AgentLoopEventInterface union.
3. The legacy (string, array) shape stays available via a ->to_legacy() method on each event class for callers that haven't migrated.
4. New events extend the same interface — observers get instanceof discrimination.

That keeps Option A's flexibility (callable, no required filter) while giving Option B's structure (typed objects, no schema drift).

Open question

Should AgentConversationCompletionDecision and the existing compaction events also become typed objects under this umbrella? They're already structured value objects; promoting them to first-class lifecycle events would unify the surface.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Cross-reading the second WordPress-side agents-api extraction effort to identify a working typed-events precedent for this issue.

[lezama]

Update: the second extraction also has the filter shape

Following up on my earlier typed-events comment: the second extraction has both halves shipping — the typed lifecycle event objects (Stream_Delta, Progress, Queued, Input_Required, Final_Result) AND a runtime filter (agents_api_event_sink) for cross-cutting observers.

Filter signature in production:

apply_filters( 'agents_api_event_sink', null, string $event, array $data );

Returns null (no value chain — observers don't transform; it's used as a "fan-out" filter, not a "transform" filter). The reference handler routes events to a log/audit pipeline.

So the design space is narrower than my original framing. Both options are already in flight there. The actual question for canonical is:

Are typed event objects and a filter complementary or redundant?

I think complementary, with this division:

• Typed lifecycle objects: emitted into the loop's on_event callable. Tightly-coupled callers (the consumer's runtime adapter, streaming layer, pending-action handler) consume these directly because they need the structured shape (e.g. Input_Required payload feeds the approval UI).
• agents_api_loop_event action / filter: the loop fires an event into the WordPress action/filter system in addition to invoking on_event. Cross-cutting observers (telemetry, audit log, dev console, replay queue) attach there without coordinating with the runtime adapter.

Worth confirming the no-double-fire concern Chris flagged — the action exists for the cross-cutting case where the consumer doesn't already own a multiplexer. If a consumer wires both a typed on_event handler and an action listener, they get the event twice. Acceptable trade if observers are idempotent; documented gotcha if not.

Or simpler: canonical only ships the typed-events on_event path; consumers that want fan-out compose their own filter on top (the second extraction's agents_api_event_sink becomes an optional adapter, not a substrate concern). That keeps canonical's surface minimal and avoids the double-fire question entirely.

Leaning toward the simpler option now — typed events as canonical, filter as consumer-side composition. Curious where you land.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Cross-reading the second extraction's existing filter implementation and reframing the canonical decision around what's actually in flight.