feat(v0.13): Native Event Stream Consumer — reference consumer for openclaw/openclaw#6467

[vivekchand]

Overview

Blocked on upstream: openclaw/openclaw#6467

What ClawMetry Already Has

SSE infrastructure is in place (dashboard.py):

• /api/logs-stream — SSE endpoint streaming log lines in real-time (line 9469)
• /api/health-stream — SSE endpoint for health check push (line 13304)
• Concurrent client limiting via _acquire_stream_slot / _release_stream_slot (lines 8480–8503)
• SSE_MAX_SECONDS = 300 cap per connection (line 118)
• JS EventSource consumers for both streams (lines 4767, 5200)
• OTLP/HTTP receiver at /v1/metrics and /v1/traces — OpenClaw pushes telemetry to ClawMetry

What ClawMetry does NOT have: a client that connects outbound to the OpenClaw gateway's event stream socket. Current data flow is push-only (OpenClaw → ClawMetry via OTLP + log tail).

What Needs to Be Added When #6467 Ships

1. Outbound socket client (Unix domain or TCP) that connects to the OpenClaw gateway event stream
2. Parser for structured JSON event envelope: agent.started, agent.step_started, agent.finished, tool.call, tool.output, tool.error, subagent.spawned, subagent.output, subagent.finished, llm.tokens, llm.reasoning
3. Route parsed events into existing _otel_store buckets where applicable (tokens → tokens, runs → runs)
4. Replace file-tail log watcher for events that the stream covers (retain JSONL fallback for older OpenClaw versions)
5. Expose parsed events to Live Feed tab

Feedback for OpenClaw API Design (to post on openclaw/openclaw#6467)

1. call_id correlation: tool.call / tool.output / tool.error must share a stable call_id so ClawMetry can match a call to its output and error without threading state
2. parent_session_key: subagent.spawned must include the parent session key for tree reconstruction — ClawMetry needs this to render subagent hierarchy (current transcript reader infers depth from indentation only)
3. Separate reasoning token count: llm.reasoning should report thinking tokens separately from output tokens — the current OTLP openclaw.tokens metric has no reasoning field, so thinking cost is invisible

Acceptance Criteria

• Outbound event stream client connects to OpenClaw gateway socket
• All event types in catalog parsed and routed
• Live Feed tab powered by event stream (file-tail fallback retained)
• call_id correlation working for tool timeline
• Subagent tree rendered from parent_session_key
• Latency < 100ms from event to UI