Adds event observability and admin capabilities

[flenter]

Agents manage a lot of state and emit many events that are important to monitor during development and in production.

While working on @fiberplane/agents, we’ve instrumented the Agent class using a mixin (previously a decorator). We’ve realized this should be built into the framework and made easily pluggable.

This PR overlaps with #238 — we should likely merge or coordinate the two.

In addition to what’s in #238, this PR:

• Records slightly different set of events (including request and outgoing events like: response and broadcast/websocket send events).

• Proposes the following changes to the framework:

  1. Admin route inside the worker to expose events stream. This enables embedded interfaces (like Django or Elixir LiveView) to be built on top for debugging or development workflows. This is exposed as an SSE stream and can be accessed via the getAgentEventStream function
  2. Added a property on the Agent that accepts an array of EventObservers (which is similar to what is proposed in feat(obs): basic agent instrumentation #238 but allows for multiple event observers).
  3. Added a secret method that returns a random string, to make guessing of the uri for events harder, though i don't think this uri should be accessible (this is also only an issue if the agent is exposed to incoming traffic from the internet)
  4. Added a listMcpConnections method so connection information is serializable/compatible with RPC

[changeset-bot]

🦋 Changeset detected

Latest commit: e61aef9

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
hono-agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[threepointone]

Thanks so much for this PR, it looks great. I'd love to figure out a way to make this work for bout fiberplane as well as our future plans.

I'm on a flight tomorrow all day so can only get to this over the weekend/early next week, let's revisit it then?

[flenter]

Sounds good. Let's do that.

[qeqqe]

This PR has several issues that needs to be fixed.

1. code duplication - In utils.ts, createResponsePayload and createRequestPayload share 90% identical code, extract the stream reading logic.

2.Unbounded memory usage - using standard stream readers in a CF Workers env has memory limits (ig around ~128MB). Unbounded stream reading can't be good here, i suggest to add stream size limits (~10MB) also chunk for large payloads

3. dependency choice - why a separate event library is needed when CF workers support standard browser EventTarget.

4. security for AI agent admin route - For agent monitoring, a simple "secret" might not be enough, try to add proper worker authentication patterns like api tokens or JWTs.