提供 WebSocket/SSE 实时事件接口供第三方客户端同步 usage logs

[xt1990xt1990]

背景

我在维护一个非官方的 macOS 菜单栏客户端：CCH Bar，用于轻量查看 Claude Code Hub 的运行中请求、最近请求、排行和渠道状态。

项目地址：
https://github.com/xt1990xt1990/Claude-Code-Hub-Bar

目前 CCH Bar 只能通过轮询 /api/v1/usage-logs 来同步“请求中 / 已完成”的状态。实际体验中，CCH Web 页面已经显示请求中后，CCH Bar 由于轮询间隔通常会有约 1-3 秒延迟；如果把轮询间隔压到 1 秒，又会增加不必要的请求量。

需求

希望 Claude Code Hub 提供一个轻量的实时事件接口，供第三方客户端订阅使用日志/运行中请求变化，实现接近无延迟同步。

建议支持 WebSocket 或 SSE 均可，例如：

• GET /api/v1/events，SSE
• GET /api/v1/ws，WebSocket
• 或专门的 GET /api/v1/usage-logs/events

期望事件

至少希望包含这些事件类型：

• usage_log.created：新请求创建，通常对应 statusCode == null
• usage_log.updated：请求状态更新，例如 statusCode 从 null 变成 200/499/5xx
• usage_log.completed：请求完成，可选，如果 updated 已能表达则不必单独提供
• usage_log.deleted 或 usage_log.hidden：可选，用于日志清理或权限变化

建议 payload

payload 可以复用 /api/v1/usage-logs 的单条 log 结构，至少包含：

{
  "type": "usage_log.updated",
  "data": {
    "id": 123,
    "createdAt": "2026-06-09T03:45:24.511Z",
    "sessionId": "...",
    "providerName": "...",
    "model": "...",
    "statusCode": null,
    "costMultiplier": "0.0050",
    "specialSettings": []
  }
}

权限和兼容性

• 复用现有 API token 鉴权即可。
• 事件可按当前 token 的可见权限过滤，和 /api/v1/usage-logs 一致。
• 建议支持断线重连：SSE 可使用 Last-Event-ID，WebSocket 可支持客户端传 cursor 或最近 log id。
• 如果实时接口不可用，第三方客户端仍可 fallback 到现有 /api/v1/usage-logs 轮询。

价值

• 第三方轻量客户端可以做到与 CCH Web 页面接近同步。
• 避免为了低延迟而高频轮询 /api/v1/usage-logs。
• 对菜单栏、移动端、小组件、通知类客户端都比较有用。

谢谢。

[github-actions]

Thank you for this well-structured feature suggestion.

Feasibility assessment:

The codebase already has several building blocks that make this feature architecturally viable:

1. Redis pub/sub framework exists — src/lib/redis/pubsub.ts provides publishCacheInvalidation() (line 205) and subscribeCacheInvalidation() (line 220) with automatic reconnection, backoff, channel state tracking, and cleanup. Currently used for 4 cache invalidation channels (cch:cache:*), but the pattern is directly extensible to usage log event channels like cch:usage_logs:created / cch:usage_logs:updated.

2. SSE utilities exist — src/lib/utils/sse.ts contains SSE parsing helpers (isSSEText, parseSSEData) used in the proxy pipeline for upstream response streaming. The project is familiar with the SSE format.

3. WebSocket server infrastructure exists — server.js (custom Node.js server) already handles WebSocket upgrades on /v1/responses for the OpenAI Responses WS protocol. This demonstrates the project can support WS endpoints, though the current WS handling is exclusively for upstream provider proxying, not for consumer-facing event streams.

4. Usage log write hooks are identifiable — In src/app/v1/_lib/proxy/response-handler.ts, usage logs are persisted via updateMessageRequestDetails() and updateMessageRequestDuration(). These are the natural insertion points for publishing usage_log.created / usage_log.updated events to Redis pub/sub.

5. Event-driven notification pattern exists — The notification system (src/lib/notification/notifier.ts) already implements push-based event delivery via webhook with Redis-based dedup and Bull queue-backed processing.

Implementation considerations:

• SSE is likely a better fit than WebSocket for this use case. SSE is simpler (HTTP-based, no upgrade needed), works natively with the existing OpenAPI Hono router in src/app/api/v1/_root/app.ts, and supports Last-Event-ID for reconnection — exactly as suggested in the issue. The management API already uses bearer/API-key/cookie auth via requireAuth() middleware (line 36-55 of app.ts), which would apply to an SSE endpoint.

• The Redis pub/sub extension would involve adding a new channel (e.g., cch:usage_logs:events) to src/lib/redis/pubsub.ts and publishing events from the response handler after updateMessageRequestDetails() completes. The existing publishCacheInvalidation() / subscribeCacheInvalidation() pattern (with auto-degradation on failure, automatic reconnection, and cleanup) serves as a ready-made template.

• Auth filtering: The existing requireAuth("read") middleware (used by GET /usage-logs in src/app/api/v1/resources/usage-logs/router.ts line 62) provides the same token-based access control. Events would need to be filtered per-connection based on the subscriber's permissions (admin vs. user scope), consistent with how listUsageLogs in handlers.ts filters by user identity.

• Dashboard co-benefit: The dashboard currently relies entirely on client-side polling (SWR / useQuery) with no real-time push. A /api/v1/usage-logs/events SSE endpoint could also benefit the built-in dashboard, not just third-party clients.

Dependencies that would be affected:

Module	Impact
src/lib/redis/pubsub.ts	New channel + publish helper for usage log events
src/app/v1/_lib/proxy/response-handler.ts	Event emission after log creation/update
src/app/api/v1/resources/usage-logs/	New SSE endpoint (router + handler)
src/app/api/v1/_root/app.ts	Route registration
server.js	Only needed if WebSocket is chosen instead of SSE

---

Automated response from Claude AI

[ding113]

感谢支持。目前正在考虑这一功能，预计会在下一季度的重构版本中提供。