feat(realtime): land LiveKit dead code + LK-based subscribe (PR 2 of 3)

[VerioN1]

Summary

Brings in the LiveKit transport layer as importable-but-mostly-unwired code, and rewires the subscribe path onto it. Publish (createRealTimeClient) is untouched and still uses the existing aiortc WebRTCManager — the final swap happens in PR 3 (the current alon/livekit-prod HEAD).

This PR is structured so that every line either belongs to the LK transport (new files) or to a strictly additive change on the existing surface. Nothing aiortc was modified for the sake of giving this PR meaning.

What lands

• New modules: stream-session.ts, signaling-channel.ts, media-channel.ts, remote-stream-exposure.ts, observability/livekit-stats-provider.ts, realtime/config-realtime.ts
• New utils: utils/media.ts (shared imageToBase64), utils/platform.ts
• RealtimeObservability gains setLiveKitRoom() that wires a LK-room stats provider into the same stats pipeline introduced in PR 1
• types.ts becomes a superset:
  • keeps every aiortc message type (OfferMessage/AnswerMessage/IceCandidateMessage/ReadyMessage/SessionIdMessage/etc.) — still consumed by webrtc-connection/webrtc-manager
  • adds LK message + domain types (LiveKitJoinMessage, LiveKitRoomInfoMessage, QueuePosition/QueuePositionMessage, ConnectionStatus, SessionStarted, InitialState, ServerError, ImageSetOptions, …)
• subscribe-client.ts is rewritten onto livekit-client + RealtimeObservability with the new room_name token format (was sid/ip/port). The aiortc-form encoder/decoder previously living here and used by the publish path's subscribeToken is inlined into realtime/client.ts so it dies cleanly when client.ts is rewritten in PR 3
• createDecartClient now exposes realtime.{ connect, subscribe } where subscribe comes from createRealTimeSubscribeClient
• Adds livekit-client@^2 to packages/sdk deps

Intentionally deferred to PR 3

• Logger default stays noopLogger (PR 3 flips to createConsoleLogger(\"info\"))
• diagnostics.ts keeps the LK-incompatible event types (IceCandidateEvent, IceStateEvent, PeerConnectionStateEvent, SignalingStateEvent, SelectedCandidatePairEvent) because aiortc publish still emits them; PR 3 drops them along with aiortc
• Publish path swap (client.ts → StreamSession, deletion of webrtc-manager.ts/webrtc-connection.ts, methods.ts rewrite, aiortc tests removal)

Tests

• Adds tests/realtime-observability-unit.test.ts and tests/realtime.unit.test.ts (the set() block from the LK branch is excluded — it depends on PR 3's methods.ts)
• A few tests/unit.test.ts assertions adjusted to the new shape:
  • removed the aiortc-form Subscribe Token round-trip block (now covered by the new room_name tests in realtime.unit.test.ts)
  • inlined the legacy decoder in the session_id populates subscribeToken test
  • removed the TelemetryReporter "warns on non-2xx" test (telemetry is now silent on non-2xx by design — .catch(() => {}))

Test plan

• pnpm typecheck clean
• pnpm test — 217/217 passing
• pnpm exec biome check . clean
• Manual smoke: producer (createDecartClient().realtime.connect) still works against existing aiortc backend
• Manual smoke: consumer (createDecartClient().realtime.subscribe) connects to a LK-backed /watch-stream token

🤖 Generated with Claude Code

---

Note

Medium Risk
Replaces the realtime subscribe implementation and reshapes the public realtime API, which may break existing consumers and introduces a new LiveKit dependency plus new connection/telemetry behavior.

Overview
Adds a new LiveKit-backed realtime stack (config, signaling/media channels, session orchestration, and a LiveKit stats adapter) and switches subscribe to use it, including a new room_name-based subscribe token and a /watch-stream/:room credential fetch.

Updates the public SDK surface so createDecartClient().realtime becomes { connect, subscribe } (splitting publish vs subscribe clients), expands realtime domain types, and centralizes realtime constants in REALTIME_CONFIG.

Observability/telemetry is updated to support LiveKit rooms as a stats source, move hardcoded thresholds/intervals/URLs into config, and make telemetry reporting best-effort/silent on failures. New unit tests cover the LiveKit subscribe flow, signaling handshake/queue behavior, retry/reconnect orchestration, and the updated observability pipeline.

^{Reviewed by Cursor Bugbot for commit a7a41d2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@decartai/sdk@138

commit: a7a41d2

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a7a41d2. Configure here.}

[cursor]

Field named "variance" actually computes standard deviation

Medium Severity

The field interFrameDelayStdDevMs was renamed to interFrameDelayVarianceMs, but the computation still calculates the standard deviation (square root of variance), not variance. The comment even still states "Report std-dev in ms." Consumers relying on this field as a variance value will get incorrect results — variance and standard deviation have different units and magnitudes (variance is in ms², std-dev is in ms).

Additional Locations (1)

• packages/sdk/src/realtime/observability/webrtc-stats.ts#L294-L303

 

^{Reviewed by Cursor Bugbot for commit a7a41d2. Configure here.}

[cursor]

Duplicate blobToBase64 and imageToBase64 in two files

Low Severity

blobToBase64 and imageToBase64 in utils/media.ts are exact duplicates of the same functions in realtime/client.ts. The new utils/media.ts exports are not imported anywhere in the codebase — they are completely unused. While the PR description says these are shared utils, client.ts still uses its own inline copies.

Additional Locations (1)

• packages/sdk/src/realtime/client.ts#L43-L92

 

^{Reviewed by Cursor Bugbot for commit a7a41d2. Configure here.}