feat(diagnostics): listen for agent_hello + warn on bad client config

[maxwell-merge-slam]

Summary

Tech World clients now publish a one-shot agent_hello data message immediately after room.connect() succeeds (Flutter PR enspyrco/tech_world#478), carrying the ConnectOptions actually in use plus SDK / build / version metadata.

This change makes both Clawd and Dreamfinder log every hello they receive and emit a structured warning when a client is connected with adaptiveStream: true — the configuration known to silently break Tech World video forwarding (and pause audio via SFU demand-signaling) because the Flutter client renders through the Flame canvas instead of VideoTrackRenderer.

Complements PR #15's publisher-side heuristic: that infers misconfiguration from a downstream symptom (track-subscribed but no first frame); this reads the cause directly off the wire.

Coupled PR

Flutter publisher: enspyrco/tech_world#478 (feat/agent-hello-diagnostic). The two PRs are independently deployable:

• This PR first → no behavior change (listener with no publisher).
• Flutter PR first → old bots silently drop the data message (no consumer).

Wire contract

Topic: agent_hello (snake_case — deliberate, agent-inbound channel naming).

Payload v1:

{
  "schemaVersion": 1,
  "clientSdk": "flutter",
  "clientSdkVersion": "2.7.0",
  "buildSha": "string",
  "appVersion": "0.0.0+1",
  "adaptiveStream": false,
  "dynacast": false,
  "platform": "macos|ios|android|web|...",
  "userAgent": "string | null"
}

Log shape

Successful parse:

{ "event": "agent_hello_received", "participant": "<identity>", "payload": { ... } }

Bad-config warning (only when adaptiveStream === true):

{ "event": "client_misconfig_detected", "warning": "adaptiveStream=true breaks Tech World video/audio forwarding", "participant": "<identity>", "clientSdkVersion": "...", "buildSha": "...", "appVersion": "..." }

Notable design choices

• New src/livekit-topics.ts to start mirroring Tech World's LiveKitTopic enum (only AGENT_HELLO today — extend opportunistically).
• parseAgentHello is a pure validator: rejects unknown schemaVersion, missing or wrong-typed fields. No throw on bad payloads; warn + drop.
• Logging via console.log / console.warn matches the rest of this codebase. Project memory mentions pino but the codebase doesn't actually have it — followed what's here.
• No persistence, no retry, no buffering. The log line is the artifact.
• Wired into BOTH src/index.ts (Clawd) and src/dreamfinder-entry.ts (DF) so every bot variant observes hellos.

Test plan

• npm run typecheck clean.
• npm run lint clean.
• npm run build clean.
• Manual: deploy alongside Flutter PR #478, watch tw-clawd / tw-dreamfinder logs for agent_hello_received lines on next player join.

🤖 Generated with Claude Code

[nickmeinhold]

Casing nit, but load-bearing: the wire string "agent_hello" should be "agent-hello" to match the kebab-case convention every other LiveKit topic uses on the Flutter side (map-info, door-unlock, chat-response, position-heartbeat, etc).

The Flutter LiveKitTopic enum is uniformly kebab; snake_case here makes agent_hello the only outlier and breaks the implicit "all topics are kebab" contract that external consumers can rely on.

One-line diff in src/livekit-topics.ts:

-  AGENT_HELLO: "agent_hello",
+  AGENT_HELLO: "agent-hello",

The TS constant name AGENT_HELLO (SCREAMING_SNAKE_CASE) stays the same — only the wire literal changes. Doc comments in src/agent-hello.ts referring to the topic by name should also update from agent_hello to agent-hello.

Coordinated comment going onto tech_world PR #478 so both ends flip together.