Wraps a user-provided event stream handler as a capability, allowing it
to participate in the capability middleware chain instead of requiring
the dedicated `event_stream_handler` argument on `Agent`/`Agent.run`.
Ordered 'outermost' so the handler sees events after all other
`wrap_run_event_stream` wrappers have transformed the stream.

Both approaches coexist: the existing `event_stream_handler` params
remain unchanged.

- Switch HandleEventStream to a tee: forward events downstream while also
  feeding the handler via an internal memory object stream. Multiple
  capabilities (and the explicit `event_stream_handler` param) can now
  observe the same stream without shadowing each other.
- Drop `outermost` ordering — no longer needed with the tee design.
- Drop the private `_agent_graph` module links from the docstring.
- Add HandleEventStream row to the capabilities.md table.

The `EventStreamHandler` type alias now accepts either an observer (async def
returning None) or a transformer (async generator yielding AgentStreamEvents).
Both forms are supported by `HandleEventStream` and the top-level
`event_stream_handler` parameter:

- Observer: the capability tees events to the handler while passing them
  through unchanged to the rest of the chain.
- Transformer: the capability iterates the handler's output and forwards
  those events to the chain, letting the handler modify, drop, or add events.

At the `event_stream_handler` parameter level the handler is the terminal
consumer, so observer and transformer are equivalent (both iterated to
completion via a shared `_consume_event_stream_handler` helper).

All three durable-exec backends (prefect, temporal, dbos) call the user's
event stream handler directly in their wrapper models/agents. Switch those
sites to the shared `consume_event_stream_handler` helper in
`agent/abstract.py` so both observer and transformer handler forms work.

…els to capability chain

- Revert `EventStreamHandler` to its original observer-only signature
  (`Awaitable[None]`). The param-level handler is a terminal consumer where
  a transformer return has nowhere to go.
- Introduce `EventStreamProcessor` (async generator yielding events) as a
  sibling type used only where transformation is meaningful.
- `HandleEventStream.handler` accepts either; it dispatches via
  `inspect.isasyncgenfunction` — tee for observers, iterate-and-yield for
  processors. Name follows the `HistoryProcessor` convention already used
  for the history-processing capability.
- Remove the cross-module `consume_event_stream_handler` helper; call sites
  just `await handler(...)` again.

Also thread the owning agent through each durable-exec model wrapper
(`TemporalModel` already had it; `DBOSModel` and `PrefectModel` now do),
and route the streamed response through `agent.root_capability.wrap_run_event_stream`
inside the activity/step before passing it to the handler. With no capability
overriding the hook this is a transparent pass-through, so existing event
stream behavior and span output are unchanged; `HandleEventStream` (and any
other capability overriding `wrap_run_event_stream`) now fires inside the
durable activity rather than being silently ignored.

Expose `root_capability` on `AbstractAgent` / `WrapperAgent` so wrapper
models can reach it polymorphically.

…le-invoke

- Extract a `run_event_stream_through_capabilities` helper in
  `agent/abstract.py` and call it from all three durable-exec model
  wrappers (DBOS/Prefect/Temporal). Replaces the gated inline code that
  was skipping capability wrapping whenever `event_stream_handler` was
  unset, so a user who registers only `HandleEventStream` on the agent
  now sees real model events inside the activity/step.
- `HandleEventStream.wrap_run_event_stream` now dispatches by inspecting
  the handler's return value (`isinstance(probe, AsyncIterator)`) rather
  than `inspect.isasyncgenfunction`, so callable-class processors whose
  `__call__` is an async generator work correctly too.
- Tee loop catches `BrokenResourceError`/`ClosedResourceError` so a
  handler that iterates once and returns no longer crashes the wrap —
  downstream consumers keep receiving events.
- In `Agent.run()`'s streaming loop, skip the outer
  `wrap_run_event_stream` pass when the stream is a
  `CompletedStreamedResponse` (the marker durable wrappers return after
  consuming events inside an activity/step). This avoids double-invoking
  the capability chain — once with real events inside the activity, again
  on an empty stream in the workflow loop.
- Tests: direct unit tests for the helper cover all branches
  (agent/no-agent × handler/no-handler); `HandleEventStream` tests cover
  callable-class processors and observer early-bailout.

- Revert the `isinstance(stream, CompletedStreamedResponse)` guard in
  `Agent.run()`'s streaming loop: `n.stream()` yields an `AgentStream`
  wrapper, not the underlying `StreamedResponse`, so the guard was a
  no-op that never triggered. The double-invocation behavior around
  durable-exec's `CompletedStreamedResponse` is real but needs a
  different fix; leaving it for a followup.
- Simplify `run_event_stream_through_capabilities`: always iterate the
  (possibly capability-wrapped) stream when no handler is provided,
  since the helper is only invoked when at least one of them needs to
  see events. Drops the stale `elif wrapped is not stream` branch.
- Tighten the direct unit tests to match the simpler helper contract.

Back out the approach where durable-exec model wrappers reached into
`self._agent.root_capability.wrap_run_event_stream(...)` to fire the
capability chain inside the activity/step. Reasons:

- Durable wrappers are documented as using only the public Agent API;
  reaching into `root_capability` crosses that line.
- The outer `AbstractAgent.run()` loop still wrapped the
  `CompletedStreamedResponse` returned from the durable call, so the
  handler fired twice per model request. A marker to suppress the
  second wrap is possible but wants more thought once PR #4977 (which
  ports durable exec to capabilities) lands.

The in-activity wrapping is removed from all three durable models and
the `run_event_stream_through_capabilities` helper is deleted.
`HandleEventStream`'s docstring now spells out the durable limitation
and points at the capability-port work. `event_stream_handler=` on the
agent continues to work inside durable runs exactly as before.

(`AbstractAgent.root_capability` abstract property and `WrapperAgent`'s
delegation stay — they're small and correct regardless of whether
durable code currently reaches for them.)

- Re-export `EventStreamProcessor` from `pydantic_ai.agent` alongside
  `EventStreamHandler`. Fixes the mkdocs cross-reference in the
  `HandleEventStream` docstring and lets users annotate processor
  handlers with the canonical import path.
- Spell out in the docstring what happens when an observer handler
  returns early (stops receiving events, downstream unaffected) vs.
  raises (exception propagates to the rest of the run).

…ink PR #4977, drop abstractmethod on root_capability

- Rename `HandleEventStream` to `ProcessEventStream` (and file `event_stream_handler.py` → `process_event_stream.py`). "Handle" underplayed the transformer form's side effects.
- Link the durable-execution note to PR #4977 so readers can follow the in-flight work.
- Drop `@abstractmethod` from `AbstractAgent.root_capability` — existing third-party subclasses shouldn't break; raising `NotImplementedError` on access is enough.