diff --git a/README.md b/README.md index 1f8fee3..d95e616 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Quorum is a child process inside the hive container, like the `spektacular` bina 1. Hive writes a fresh random bearer token to a file at boot, and the tenant's Vexa API key (and, if used, the Discord bot token) from its keystore to files. 2. Hive starts `node quorum.mjs serve` with the `QUORUM_*` variables below and supervises it. `GET /healthz` answers `{"ok":true,...}` once it is listening. -3. Hive is the MCP client: `POST http://127.0.0.1:8765/mcp` with `Authorization: Bearer ` (streamable HTTP, stateless, JSON responses). Tools: `meeting.join`, `meeting.leave`, `meeting.status`, `transcript.read`, `chat.post`, `say`, `say.tone` (the soft listening chime: played by the Vexa bot, and by quorum itself on Discord), `say.prewarm`, `meeting.delete`. Every result is `{ok:true,...}` or `{ok:false,error:{code,message}}` in `structuredContent` and as JSON text. +3. Hive is the MCP client: `POST http://127.0.0.1:8765/mcp` with `Authorization: Bearer ` (streamable HTTP, stateless, JSON responses). Tools: `meeting.join`, `meeting.leave`, `meeting.status`, `transcript.read`, `chat.post`, `say`, `say.tone` (the soft listening chime: played by the Vexa bot, by quorum itself on Discord, and by the desktop companion on the host's computer), `say.prewarm`, `meeting.delete`. Every result is `{ok:true,...}` or `{ok:false,error:{code,message}}` in `structuredContent` and as JSON text. 4. Hive follows each meeting on `GET /events?meeting_id=` (Server-Sent Events, same bearer): `segment`, `chat` and `state` events, one JSON object per `data:` line, `id:` = `seq`. Reconnect with `after_seq=` to replay what was missed. `GET /events` without `meeting_id` carries every meeting, including Discord `/hive join` requests. 5. On SIGTERM quorum leaves Discord channels and exits. Vexa bots keep running until hive calls `meeting.leave`; a restarted quorum that is asked to join the same meeting adopts the running bot. @@ -64,6 +64,8 @@ Secrets are only ever read from files, on use, so hive can rotate them without a | `QUORUM_COMPANION_MAX_SEGMENT_S` | `20` | Longer companion speech is cut into segments of this length. | | `QUORUM_COMPANION_VAD_THRESHOLD` | `500` | Frame RMS (int16 scale) that counts as speech. | | `QUORUM_COMPANION_OUTBOX_MAX` | `200` | Lines kept for the companion window. | +| `QUORUM_COMPANION_CONNECTED_MS` | `5000` | A companion that fetched its outbox this recently is connected: `say.tone` only plays for a connected companion. | +| `QUORUM_COMPANION_TONE_TTL_MS` | `4000` | A listening tone the companion has not fetched this long after `say.tone` is dropped, so a late chime never plays. | | `QUORUM_TTS_TIMEOUT_MS` | `30000` | Timeout for each TTS request. | | `QUORUM_CHAT_MAX_CHARS` | `2000` | Longest `chat.post` text. | | `QUORUM_CHAT_CONFIRM_TIMEOUT_MS` | `30000` | How long `chat.post {confirm:true}` waits for Vexa to report the line posted or failed. | diff --git a/docs/contract.md b/docs/contract.md index 7261415..c01db2d 100644 --- a/docs/contract.md +++ b/docs/contract.md @@ -14,7 +14,7 @@ Quorum runs **inside the hive container** as a child process that hive starts an - Whisper for Discord audio: `QUORUM_TRANSCRIBE_URL` (the shared CPU transcription service), optional `QUORUM_TRANSCRIBE_TOKEN_FILE`. Each request sends the bot's display name (and its first word) plus `QUORUM_TRANSCRIBE_HOTWORDS` (comma-separated vocabulary; default `Betty, leave, hive, hive queue, pull request, PR, issue, board pressure, crux, dibs, docs, homebrew-hive, hotshot, pluk, promptargs, rationguard, quorum, vexa, quorum-companion, Kubernetes, KubeCon, CNCF, Spektacular, Spek, Plaud, RFC, inbox, spoke, hub`) as the Whisper `prompt`, and each name's first word as `hotwords` (a service without that field ignores it), so the bot's own name is spelled right. A request answered 429 or 5xx, or never answered, is retried up to `QUORUM_TRANSCRIBE_MAX_ATTEMPTS`=4 tries in all, with exponential backoff and full jitter from `QUORUM_TRANSCRIBE_BACKOFF_BASE_MS`=250 capped at `QUORUM_TRANSCRIBE_BACKOFF_MAX_MS`=4000 (a `Retry-After` is honoured up to that cap); only then is the segment dropped, logged with the attempt count. One speaker's segments are transcribed in order. Before a Discord segment is sent, its leading and trailing silence is cut (20 ms frames below `QUORUM_DISCORD_VAD_THRESHOLD`=500 RMS on the int16 scale, 200 ms kept each side); a segment with less than `QUORUM_DISCORD_MIN_SEGMENT_MS` of speech left is not sent. While the service is busy, a speaker's waiting segments are merged into one request (up to `QUORUM_DISCORD_MAX_SEGMENT_S` of audio) rather than queued one request each. - Speech on Discord: `QUORUM_TTS_URL` (the shared Kokoro service, OpenAI-compatible `/v1/audio/speech`), optional `QUORUM_TTS_TOKEN_FILE` (sent as `X-API-Key`), `QUORUM_TTS_VOICE` (default `af_heart`), `QUORUM_TTS_TIMEOUT_MS`=30000 per request. Without `QUORUM_TTS_URL`, Discord `say` returns `platform_unavailable`. Synthesized sentences are kept for reuse, keyed by voice and text and shared by every meeting, up to `QUORUM_TTS_CACHE_MAX_BYTES`=33554432 of 24 kHz mono PCM (least recently used dropped first); `say.prewarm` fills that cache, at most `QUORUM_SAY_PREWARM_MAX_LINES`=32 lines a call. - Leaving: `meeting.leave` first waits up to `QUORUM_LEAVE_DRAIN_TIMEOUT_MS`=8000 for speech and chat already on their way (0 turns the wait off). On Vexa a spoken line's playback record is read every `QUORUM_SAY_POLL_MS`=200. -- Companion (desktop app audio, hivecommons/quorum-companion): always registered; needs `QUORUM_TRANSCRIBE_URL` (else `meeting.join` answers `platform_unavailable`). Limits: `QUORUM_COMPANION_MAX_CHUNK_BYTES`=131072, `QUORUM_COMPANION_SILENCE_MS`=500, `QUORUM_COMPANION_EARLY_MS`=100 (0 turns early transcription off), `QUORUM_COMPANION_MIN_SPEECH_MS`=300, `QUORUM_COMPANION_MAX_SEGMENT_S`=20, `QUORUM_COMPANION_VAD_THRESHOLD`=500 (frame RMS on the int16 scale), `QUORUM_COMPANION_OUTBOX_MAX`=200. +- Companion (desktop app audio, hivecommons/quorum-companion): always registered; needs `QUORUM_TRANSCRIBE_URL` (else `meeting.join` answers `platform_unavailable`). Limits: `QUORUM_COMPANION_MAX_CHUNK_BYTES`=131072, `QUORUM_COMPANION_SILENCE_MS`=500, `QUORUM_COMPANION_EARLY_MS`=100 (0 turns early transcription off), `QUORUM_COMPANION_MIN_SPEECH_MS`=300, `QUORUM_COMPANION_MAX_SEGMENT_S`=20, `QUORUM_COMPANION_VAD_THRESHOLD`=500 (frame RMS on the int16 scale), `QUORUM_COMPANION_OUTBOX_MAX`=200, `QUORUM_COMPANION_CONNECTED_MS`=5000, `QUORUM_COMPANION_TONE_TTL_MS`=4000. - Typed chat on Discord needs the privileged MessageContent intent, which the operator enables for the bot in the Discord developer portal. If Discord refuses it, quorum logs a warning once and connects without it: voice, transcripts and `chat.post` keep working, and no typed `chat` events arrive. - Every numeric limit in this file is an env var with the default shown. @@ -30,7 +30,7 @@ All tools return `{ok: true, ...}` or `{ok: false, error: {code, message}}`, as | `transcript.read` | `{meeting_id, after_seq?}` | `{segments:[Segment], next_seq}` final segments only, oldest first; `next_seq` is the cursor to pass back as `after_seq` | | `chat.post` | `{meeting_id, text, confirm?}` text max `QUORUM_CHAT_MAX_CHARS`=2000 | `{posted_at, delivery}`. `delivery` is `confirmed` when the platform reports the line in the meeting, else `unconfirmed`. Without `confirm` quorum does not wait: Discord answers `confirmed` (its send returns once the message exists), Vexa `unconfirmed` (the bot only received the line). With `confirm:true` on Vexa, quorum reads the send's delivery record (`GET /bots/{platform}/{native_id}/chat/{request_id}`) every `QUORUM_CHAT_CONFIRM_POLL_MS`=500 for up to `QUORUM_CHAT_CONFIRM_TIMEOUT_MS`=30000 (the Teams bot alone may wait 10 s for the chat composer after admission): `confirmed` once the bot reports it posted, `platform_unavailable` (message names the bot's reason, for example `no_composer` when the meeting chat is not open to the bot) when it reports the send failed, and `unconfirmed` when no verdict came in time or Vexa has no delivery route. A caller that must know the line was seen (the consent notice) passes `confirm:true` and treats `unconfirmed` as not posted. | | `say` | `{meeting_id, text}` text max `QUORUM_SAY_MAX_CHARS`=1000 | `{queued:true, duration_ms?, first_audio_ms?, synth_ms?, cached?}`. Lines of one meeting play one after another, never over each other. On Discord a line is spoken sentence by sentence: the text is cut at `.`, `!`, `?` or `:` followed by whitespace (a closing quote or bracket stays with its sentence; pieces under 24 characters are joined to a neighbour; text with no such break is one sentence), the sentences are synthesized one after another, and each is queued for playback in order as soon as it is ready, so the first sound comes after one sentence's synthesis. The call resolves once the first sentence is ready (playback is queued behind earlier lines). If the first sentence cannot be synthesized the call answers `upstream_error` and nothing of that line is spoken; a later sentence that fails is skipped and logged, and the sentences after it still play. Each sentence's clip gets a 5 ms fade in and out and is cached by voice and text. `duration_ms` (whole milliseconds) is the line's real audio length when known: on Discord only when every sentence was ready by the time the call resolved (a one-sentence line, or a line whose sentences were all cached), on Vexa when the bot reports it. `first_audio_ms` is the time from the request to the first audio: on Discord until the first sentence was handed to the playback queue; on Vexa the bot's own `first_audio_ms` when the playback record has it, else the time until quorum first read the record as `speaking` or `spoken` (late by at most one poll), present only when the line was reported `spoken`. `synth_ms` is the synthesis time before the first audio: on Discord 0 when the whole line came from the cache, else equal to `first_audio_ms`; on Vexa the record's `synth_ms` when it has one. `cached` says every sentence of the line came from the clip cache (Discord), or is the record's `cached` when it has one (Vexa). On Vexa each say is sent only after the meeting's previous say settled; when the speak answer carries a `request_id`, quorum reads the line's playback record (`GET /bots/{platform}/{native_id}/speak/{request_id}`, statuses `queued`, `speaking`, `spoken` with `duration_ms` and, from a bot that reports them, `first_audio_ms`, `synth_ms` and `cached`, `failed` with `reason`) every `QUORUM_SAY_POLL_MS`=200 for up to `QUORUM_SAY_CONFIRM_TIMEOUT_MS`=60000 and resolves once it is `spoken` (or with no verdict in time, or no such route). `platform_unavailable` when the bot was started without voice or Vexa refuses speech (404/409, message `speak is not available: `), when the bot reports the line `failed` (message `the line was not spoken: `, for example `mic_muted`), or when `QUORUM_TTS_URL` is unset (Discord); `upstream_error` when the TTS service fails on the line's first sentence (Discord) | -| `say.tone` | `{meeting_id}`; the meeting must be live (else `not_live`) | `{played}`. Plays the listening tone: a short, soft chime, not speech, that tells the room the bot heard its name and is about to answer. It never waits for the sound and never queues behind speech: `played` is `false` when it was dropped on purpose (a `say` is in progress, the bot has no voice, the bot refused it, or the platform has no tone: the companion). On Discord quorum renders the chime in code (two sine notes, G5 then C6, about 200 ms, peak at 18% of full scale with a smooth attack and release, so it cannot click) and plays it into the voice channel at once, asynchronously; it is dropped (`played:false`) when a `say` is queued or playing, when a tone is already playing, when `QUORUM_TTS_URL` is unset (the bot has no voice) or when the bot is not in the channel, and a `say` that starts during the chime cuts it. On Vexa the bot synthesizes the chime itself and plays it at once; it is requested through the speak route with the reserved line `[[hive:listening-tone]]`, so a person never has that line spoken. | +| `say.tone` | `{meeting_id}`; the meeting must be live (else `not_live`) | `{played}`. Plays the listening tone: a short, soft chime, not speech, that tells the room the bot heard its name and is about to answer. It never waits for the sound and never queues behind speech: `played` is `false` when it was dropped on purpose (a `say` is in progress, the bot has no voice, the bot refused it, or the companion is not connected). On Discord quorum renders the chime in code (two sine notes, G5 then C6, about 200 ms, peak at 18% of full scale with a smooth attack and release, so it cannot click) and plays it into the voice channel at once, asynchronously; it is dropped (`played:false`) when a `say` is queued or playing, when a tone is already playing, when `QUORUM_TTS_URL` is unset (the bot has no voice) or when the bot is not in the channel, and a `say` that starts during the chime cuts it. On Vexa the bot synthesizes the chime itself and plays it at once; it is requested through the speak route with the reserved line `[[hive:listening-tone]]`, so a person never has that line spoken. On the companion the desktop app plays the same chime on the host's own computer (see Companion audio). | | `say.prewarm` | `{meeting_id, texts}` `texts` is 1 to `QUORUM_SAY_PREWARM_MAX_LINES`=32 non-empty strings, each at most `QUORUM_SAY_MAX_CHARS` (else `invalid_argument`); the meeting must be live (else `not_live`) | `{queued}`. Gets fixed lines (an introduction, acknowledgements, a goodbye) ready so a later `say` of the same text starts at once. On Discord each line is cut into sentences as `say` does and every sentence not yet cached is synthesized in the background with the meeting's voice, one request at a time; `queued` is the number of sentences sent for synthesis (0 when all were ready or already on their way). A sentence that fails is skipped and synthesized when it is said. Nothing is played. `queued` is 0 on platforms without their own synthesis in quorum: Vexa (its bot synthesizes), the companion, and Discord without `QUORUM_TTS_URL`. | | `meeting.delete` | `{meeting_id}` | `{deleted:true}` erases transcript upstream | @@ -52,7 +52,8 @@ A companion meeting has no bot in any meeting: a desktop app on a person's own c - Each channel is cut into utterances at `QUORUM_COMPANION_SILENCE_MS` of silence (or at `QUORUM_COMPANION_MAX_SEGMENT_S`), utterances under `QUORUM_COMPANION_MIN_SPEECH_MS` of speech are dropped, and each one is transcribed by the shared service, one at a time per meeting. Final segments are ordinary `segment` events: `speaker` is `{id:"host", name:}` for `mic` and `{id:"call", name:"Call"}` for `call` (the meeting client mixes everyone else). `meeting.leave` transcribes any open utterance before the `ended` state. - Early transcription: the end of an utterance is only known once `QUORUM_COMPANION_SILENCE_MS` of silence followed it, and the companion sends audio in chunks, so quorum does not wait for it. As soon as an open utterance with at least `QUORUM_COMPANION_MIN_SPEECH_MS` of speech is followed by `QUORUM_COMPANION_EARLY_MS`=100 of silence, it is transcribed ahead of its end, with one attempt (no retries) and at most once per pause. The clip sent is the utterance so far padded with digital silence until its trailing silence is `QUORUM_COMPANION_SILENCE_MS` long, the clip the utterance would be sent as once it ended (a clip that stops right after the last word makes Whisper invent a continuation). If the answer arrives while the utterance is still open and unchanged, it is published as a draft segment (`final:false`), so draft segments now also appear on companion meetings. When the silence then runs its full length with no more speech, the same answer becomes the final segment (`final:true`, the same text) without a second request. If the speaker carries on, the early answer is dropped and the utterance is transcribed whole when it ends, as it is when the early request failed. A draft is never published after its final. `QUORUM_COMPANION_EARLY_MS`=0 turns this off: every utterance is transcribed once, when it ends. - Every final companion segment logs one info line `companion: segment timing` with `seq`, `channel` (`call` or `mic`), `clip_ms` (the utterance's length), `capture_ms` (the last speech sample to the arrival of the chunk holding it: the companion's chunking and the network), `endpoint_ms` (that arrival to the end of the utterance being known), `stt_ms` (the transcription request that gave the text), `total_ms` (the last speech sample to the segment event) and `early` (true when the text came from the early transcription, so `stt_ms` overlapped the wait for the end). -- `chat.post` queues the line for the companion window instead of a meeting chat. `GET /companion/outbox?meeting_id=&after=N` returns `{lines:[{seq,text,at}], next_seq}`; fetching lines marks them delivered, so `chat.post` with `confirm:true` answers `confirmed` once the companion fetched the line and `unconfirmed` after `QUORUM_CHAT_CONFIRM_TIMEOUT_MS`. Without `confirm` it answers `unconfirmed`. The outbox keeps the last `QUORUM_COMPANION_OUTBOX_MAX` lines. +- `chat.post` queues the line for the companion window instead of a meeting chat. `GET /companion/outbox?meeting_id=&after=N` returns `{lines:[{seq,text,at}], next_seq, tone}`; fetching lines marks them delivered, so `chat.post` with `confirm:true` answers `confirmed` once the companion fetched the line and `unconfirmed` after `QUORUM_CHAT_CONFIRM_TIMEOUT_MS`. Without `confirm` it answers `unconfirmed`. The outbox keeps the last `QUORUM_COMPANION_OUTBOX_MAX` lines. +- `say.tone` hands the listening tone to the companion, which plays the chime itself on the host's computer (never into the call). It answers `played:true` only while the companion is connected, i.e. it fetched `/companion/outbox` within `QUORUM_COMPANION_CONNECTED_MS`, and `played:false` otherwise or while an earlier tone still waits to be fetched. The next outbox fetch answers `tone:true` once (fetching delivers it, like lines; otherwise `tone:false`). A tone not fetched within `QUORUM_COMPANION_TONE_TTL_MS` is dropped, so a late chime never plays. The companion renders the same chime as `src/tone.ts` (24 kHz mono, G5 then C6, 100 ms each, 8 ms attack, 25 ms release, decay to 0.12, peak 0.18 of full scale). - `say` answers `platform_unavailable` (spoken replies through a virtual microphone are a later step); `say.prewarm` answers `{queued:0}`. The companion's own consent prompt is the consent gate for these meetings; hive records it. ## 2. Spektacular live mode (hive runs it as a child) diff --git a/src/companion/adapter.ts b/src/companion/adapter.ts index 69418a6..58fba06 100644 --- a/src/companion/adapter.ts +++ b/src/companion/adapter.ts @@ -39,6 +39,11 @@ import { * * Every final segment logs one `companion: segment timing` line with the stages from the last * speech sample to the segment event (see SegmentTiming). + * + * The listening tone (say.tone) is played by the companion on the person's own computer: tone() + * marks one tone pending and the next outbox fetch carries `tone:true` once. It is only asked for + * while the companion is fetching its outbox (connected), and a tone left unfetched past + * QUORUM_COMPANION_TONE_TTL_MS is dropped, so a late chime never plays. */ export const COMPANION_CHANNELS = ["call", "mic"] as const; @@ -68,6 +73,14 @@ export interface OutboxLine { at: string; } +/** GET /companion/outbox. */ +export interface CompanionOutbox { + lines: OutboxLine[]; + next_seq: number; + /** Play the listening tone now (once per tone asked for). */ + tone: boolean; +} + /** An utterance transcribed ahead of its end; `text` is undefined when the request failed. */ interface Early { startMs: number; @@ -115,6 +128,10 @@ interface Live { outboxSeq: number; /** Highest outbox seq the companion has fetched. */ readSeq: number; + /** When the companion last fetched its outbox (undefined: never). */ + polledAt: number | undefined; + /** When the pending listening tone was asked for (undefined: none pending). */ + toneAt: number | undefined; /** Transcriptions run one after another so segments stay in spoken order. */ chain: Promise; } @@ -170,6 +187,8 @@ export class CompanionAdapter implements PlatformAdapter { outbox: [], outboxSeq: 0, readSeq: 0, + polledAt: undefined, + toneAt: undefined, chain: Promise.resolve(), }); meeting.setState("live"); @@ -385,18 +404,54 @@ export class CompanionAdapter implements PlatformAdapter { this.opts.log.info("companion: segment timing", { seq: segment.seq, ...timing }); } - /** Lines for the companion window after `after`; fetching them marks them delivered. */ - outbox(meeting: Meeting, after: number): { lines: OutboxLine[]; next_seq: number } { + /** + * Lines for the companion window after `after`; fetching them marks them delivered. `tone` is + * true once per listening tone asked for since the last fetch, while it is still fresh. + */ + outbox(meeting: Meeting, after: number): CompanionOutbox { const live = this.live.get(meeting.id); if (!live) { throw new QuorumError("not_live", `the meeting is ${meeting.state}, not live`); } + const now = this.now(); + live.polledAt = now; + const tone = this.toneFresh(live, now); + live.toneAt = undefined; const lines = live.outbox.filter((l) => l.seq > after); const last = lines.at(-1); if (last && last.seq > live.readSeq) { live.readSeq = last.seq; } - return { lines, next_seq: last ? last.seq : Math.max(after, 0) }; + return { lines, next_seq: last ? last.seq : Math.max(after, 0), tone }; + } + + /** Whether a pending tone is still worth playing. */ + private toneFresh(live: Live, now: number): boolean { + return live.toneAt !== undefined && now - live.toneAt <= this.opts.config.companionToneTtlMs; + } + + /** + * Asks the companion to play the listening tone. Played (true) only while the companion is + * connected, i.e. it fetched its outbox within QUORUM_COMPANION_CONNECTED_MS; dropped (false) + * when it is not, or when a tone is already waiting to be fetched. The companion never speaks, + * so no line can be in progress. Never waits and never throws. + */ + async tone(meeting: Meeting): Promise { + const live = this.live.get(meeting.id); + if (!live || meeting.state !== "live") { + return false; + } + const now = this.now(); + const connected = + live.polledAt !== undefined && now - live.polledAt <= this.opts.config.companionConnectedMs; + if (!connected) { + return false; + } + if (this.toneFresh(live, now)) { + return false; + } + live.toneAt = now; + return true; } async leave(meeting: Meeting): Promise { diff --git a/src/config.ts b/src/config.ts index 8711833..c0b0b27 100644 --- a/src/config.ts +++ b/src/config.ts @@ -62,6 +62,8 @@ export const DEFAULTS = { companionMaxSegmentS: 20, companionVadThreshold: 500, companionOutboxMax: 200, + companionConnectedMs: 5000, + companionToneTtlMs: 4000, } as const; export type DiscordCommandScope = "guild" | "global" | "off"; @@ -130,6 +132,10 @@ export interface Config { companionMaxSegmentS: number; companionVadThreshold: number; companionOutboxMax: number; + /** A companion that fetched its outbox this recently is connected and can play the tone. */ + companionConnectedMs: number; + /** A listening tone the companion has not fetched this long after it was asked for is dropped. */ + companionToneTtlMs: number; logLevel: string | undefined; } @@ -342,6 +348,16 @@ export function loadConfig(env: Env = process.env): Config { "QUORUM_COMPANION_OUTBOX_MAX", DEFAULTS.companionOutboxMax, ), + companionConnectedMs: positiveInt( + env, + "QUORUM_COMPANION_CONNECTED_MS", + DEFAULTS.companionConnectedMs, + ), + companionToneTtlMs: positiveInt( + env, + "QUORUM_COMPANION_TONE_TTL_MS", + DEFAULTS.companionToneTtlMs, + ), logLevel: optional(env, "QUORUM_LOG_LEVEL"), }; } diff --git a/test/companion.test.ts b/test/companion.test.ts index 13f7a42..ea12ccc 100644 --- a/test/companion.test.ts +++ b/test/companion.test.ts @@ -141,6 +141,69 @@ describe("companion adapter without the platform plumbing", () => { }); }); +describe("companion listening tone", () => { + const CONNECTED_MS = 5000; + const TTL_MS = 4000; + const T0 = 50_000; + + async function rig() { + const clock = { ms: T0 }; + const adapter = new CompanionAdapter({ + config: loadConfig({ + QUORUM_COMPANION_CONNECTED_MS: String(CONNECTED_MS), + QUORUM_COMPANION_TONE_TTL_MS: String(TTL_MS), + }), + log: silentLogger, + transcriber: { transcribe: () => Promise.resolve("") } as unknown as Transcriber, + now: () => clock.ms, + }); + const meeting = new Meeting({ platform: "companion", bufferSize: 10 }); + await adapter.join(meeting, { displayName: "Betty", voice: false }); + return { adapter, meeting, clock }; + } + + it("is dropped until the companion is fetching its outbox, then delivered once", async () => { + const r = await rig(); + // No fetch yet: nobody would hear it. + expect(await r.adapter.tone(r.meeting)).toBe(false); + expect(r.adapter.outbox(r.meeting, 0)).toEqual({ lines: [], next_seq: 0, tone: false }); + r.clock.ms += 1000; + expect(await r.adapter.tone(r.meeting)).toBe(true); + // A second tone while the first waits to be fetched is dropped: one chime. + expect(await r.adapter.tone(r.meeting)).toBe(false); + r.clock.ms += 1000; + expect(r.adapter.outbox(r.meeting, 0).tone).toBe(true); + expect(r.adapter.outbox(r.meeting, 0).tone).toBe(false); + // Fetched, so the next one plays again. + expect(await r.adapter.tone(r.meeting)).toBe(true); + expect(r.adapter.outbox(r.meeting, 0).tone).toBe(true); + }); + + it("is dropped once the companion stopped fetching, and expires when nobody fetches it", async () => { + const r = await rig(); + r.adapter.outbox(r.meeting, 0); + r.clock.ms += CONNECTED_MS + 1; + expect(await r.adapter.tone(r.meeting)).toBe(false); + r.adapter.outbox(r.meeting, 0); + expect(await r.adapter.tone(r.meeting)).toBe(true); + // Still connected, and the unfetched tone expired: it does not block the next one. + r.clock.ms += TTL_MS + 1; + expect(await r.adapter.tone(r.meeting)).toBe(true); + // Fetched too late: a stale chime never plays. + r.clock.ms += TTL_MS + 1; + expect(r.adapter.outbox(r.meeting, 0).tone).toBe(false); + }); + + it("never plays for a meeting that left and never throws", async () => { + const r = await rig(); + r.adapter.outbox(r.meeting, 0); + await r.adapter.leave(r.meeting); + expect(await r.adapter.tone(r.meeting)).toBe(false); + const other = new Meeting({ platform: "companion", bufferSize: 10 }); + expect(await r.adapter.tone(other)).toBe(false); + }); +}); + describe("companion early transcription", () => { const SILENCE_MS = 500; const EARLY_MS = 150; @@ -532,7 +595,7 @@ describe("companion platform end to end", () => { expect(body.next_seq).toBe(2); expect(await confirming).toMatchObject({ ok: true, delivery: "confirmed" }); const later = (await (await outbox(id, "2")).json()) as { lines: unknown[]; next_seq: number }; - expect(later).toEqual({ lines: [], next_seq: 2 }); + expect(later).toEqual({ lines: [], next_seq: 2, tone: false }); const unread = await harness().call("chat.post", { meeting_id: id, text: "nobody reads", @@ -544,6 +607,18 @@ describe("companion platform end to end", () => { expect((await outbox("m_missing")).status).toBe(404); }); + it("hands the listening tone to the companion through its outbox once it is connected", async () => { + const id = await join(); + const chime = () => harness().call("say.tone", { meeting_id: id }); + // The companion has not fetched anything yet, so nobody would hear the chime. + expect(await chime()).toEqual({ ok: true, played: false }); + expect(await (await outbox(id)).json()).toMatchObject({ tone: false }); + expect(await chime()).toEqual({ ok: true, played: true }); + expect(await chime()).toEqual({ ok: true, played: false }); + expect(await (await outbox(id)).json()).toEqual({ lines: [], next_seq: 0, tone: true }); + expect(await (await outbox(id)).json()).toMatchObject({ tone: false }); + }); + it("cannot speak, refuses long host names, and flushes speech on leave", async () => { const long = await harness().call("meeting.join", { platform: "companion", diff --git a/test/config.test.ts b/test/config.test.ts index 35e1dd7..b5fa8f2 100644 --- a/test/config.test.ts +++ b/test/config.test.ts @@ -54,6 +54,8 @@ describe("loadConfig", () => { sayPrewarmMaxLines: 32, sayPollMs: 200, companionEarlyMs: 100, + companionConnectedMs: 5000, + companionToneTtlMs: 4000, }); }); @@ -74,6 +76,9 @@ describe("loadConfig", () => { companionEarlyMs: 0, }); expect(loadConfig({ QUORUM_COMPANION_EARLY_MS: "250" }).companionEarlyMs).toBe(250); + expect( + loadConfig({ QUORUM_COMPANION_CONNECTED_MS: "9000", QUORUM_COMPANION_TONE_TTL_MS: "1500" }), + ).toMatchObject({ companionConnectedMs: 9000, companionToneTtlMs: 1500 }); }); it("sends the project's vocabulary as default hotwords, the name, leave and hive first", () => {