usertest: voice-moderated sessions with a Claude moderator

[michielbdejong]

Adds voice-moderated user-testing sessions to the test instance from #182, so testers can do a session on their own laptop without anyone from the team on a call.

What a tester gets

One invite link: https://plugins.<base-domain>/usertest/?code=…, Chrome or Edge, headphones. The page (usertest/page/):

1. explains the session and asks consent for what is recorded and where it goes: screen and microphone to the test server, speech through Google's recognizer, text and the app's error log to Anthropic's API;
2. sets the test catalog (same origin as the data-browser), opens a fresh drive in a second window, and records the shared screen and the microphone in 10-second chunks;
3. listens with SpeechRecognition and hands a turn to the moderator after a pause (3 s after a question, 9 s otherwise), after 60 s of silence, or when the collector logs a new error; then speaks the answer with speechSynthesis. Recognition pauses while the moderator speaks.

The moderator

usertest/moderator/server.mjs, with @anthropic-ai/sdk 0.128.0:

• claude-opus-5, output_config.effort: "low" for short pauses, server-side refusal fallback (fallbacks: "default"), top-level prompt caching;
• the interview script usertest/moderator/script.md: spoken one-or-two-sentence turns, mostly listening ([WAIT]), no hints unless the tester is stuck and asks, neutral about the app, four tasks (import calendar events, change one and send it back, explore other apps, wrap-up), then [END];
• each turn includes the collector's error, warning, feedback and sync lines since the previous one;
• per session /var/lib/usertest-sessions/<id>/: meta.json, transcript.jsonl (both sides, the log lines each turn saw, token usage) and recording.webm.

The endpoints spend API money and are public, so they need the invite code (x-usertest-code, from /etc/usertest-moderator.env). There are at most 120 turns per session and 20 sessions per UTC day. The API key stays in /etc/anthropic.env, read only by the moderator container.

Checked

On the droplet, over the real API:

• the opening turn (welcome plus first task) in about 3 s;
• thinking aloud answered with [WAIT] (nothing spoken);
• "which button should I press?" answered with a question, not a hint;
• cache_read_input_tokens 989 to 1088 from the second turn on;
• requests without the code get 403.

oxlint and oxfmt over the new files are clean. node --check passes for both scripts.

Not verified yet: a full session with a real tester, screen and microphone permissions in the page, speech recognition quality in Dutch, and Edge.

🤖 Generated with Claude Code