[Feature]: Agent bus — outbound WebSocket state events

[rosspeili]

One-line summary

Push state change events over the agent bus WebSocket (avatar, environment, animation, audio status) so clients can subscribe instead of polling GET /v1/state.

Problem / motivation

#6 shipped inbound WebSocket command handling, but integrators and future MCP adapters still poll GET /v1/state after every command. Reactive UIs (companion dashboards, multi-agent orchestration) need low-latency notifications when the user changes settings in-app or when a VRMA one-shot finishes.

Proposed solution

1. Define a small event envelope: { type, ts, payload } for e.g. state.snapshot, animation.started, animation.finished, environment.changed, avatar.changed, audio.status.
2. Emit on the existing loopback WebSocket when internal stage/settings hooks fire (same sources that update GET /v1/state).
3. Optional: client subscribe filter (?topics=animation,audio) to reduce noise.
4. Document event schema in docs/agents/local-bus.md; version alongside HTTP API.

Non-goals v1: guaranteed delivery / replay buffer, cross-machine streaming. Pairs naturally with the MCP adapter follow-up once both exist.

Alternatives considered

• Poll-only — simple but wasteful and misses user-initiated changes.
• SSE on HTTP — viable; WS already exists for bus, extend it first.

Primary surface

Agent / external triggers (roadmap)

Constraints you accept

• Should stay usable offline / local-first
• Browser-only mode may remain limited vs Electron

Mock / sketch / reference (optional)

Example client log:

{ "type": "animation.finished", "ts": "...", "payload": { "clip": "VRMA_03", "mode": "once" } }