Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-companion-listening-tone.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Betty's listening chime now plays in companion meetings: the companion replies route carries `tone` (true once, from Quorum's `say.tone` outbox signal), and the live session no longer refuses the tone because a companion meeting has no voice in the call, since the desktop companion plays it on the host's own computer ([quorum-companion#12](https://github.com/hivecommons/quorum-companion/issues/12)). `meetings.listening_tone` and `meetings.voice_on_address` still apply.
4 changes: 2 additions & 2 deletions src/cmd/hive/meetings_companion_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ func (q *companionStubQuorum) CompanionAudio(_ context.Context, _, _ string, seq
return meetings.CompanionChunk{Seq: seq}, nil
}

func (q *companionStubQuorum) CompanionOutbox(context.Context, string, int64) ([]meetings.CompanionLine, int64, error) {
return []meetings.CompanionLine{{Seq: 1, Text: "consent"}}, 1, nil
func (q *companionStubQuorum) CompanionOutbox(context.Context, string, int64) (meetings.CompanionPage, error) {
return meetings.CompanionPage{Lines: []meetings.CompanionLine{{Seq: 1, Text: "consent"}}, NextSeq: 1}, nil
}

func TestMeetingsDashboardCompanion(t *testing.T) {
Expand Down
6 changes: 3 additions & 3 deletions src/docs/meetings.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,15 +197,15 @@ The desktop companion ([hivecommons/quorum-companion](https://github.com/hivecom
- **Who can use it.** Owner or read-write users. A companion meeting can be used only by the person who started it (owners can use any). Read-only users cannot stream.
- **Signing in.** Each owner or read-write user opens `/companion/token` on their hive and creates a companion token (shown once; only its SHA-256 is stored, one per user, **Replace** or **Revoke** any time). The companion sends it as `X-Hive-Companion-Token`. It works only on the `/api/companion/info` and `/api/companion/meetings` routes, acts as that user at their current role (a user removed or downgraded below read-write stops working at once), and never in `Authorization`. On hosted hives the hub lets those routes through to the hive, which does the check; the token page stays behind the hub sign-in.
- **Audio.** Two channels of raw 16 kHz mono s16le PCM: `call` (the meeting app's audio, everyone else) and `mic` (the person). Quorum cuts each at silences and transcribes it with the shared transcription service (`meetings.transcribe_url` is required); `mic` segments are attributed to the person, `call` segments to "Call".
- **Betty's replies** go to the companion window (and the meeting panel) instead of a meeting chat: the consent notice first, then answers. Betty cannot speak in a companion meeting yet. Saying "betty leave" ends the meeting, as does stopping the capture. The lines still waiting when the meeting ends ("Leaving now." among them) are served by the replies route after the end, until the window's cursor has passed them or two minutes are over.
- **Betty's replies** go to the companion window (and the meeting panel) instead of a meeting chat: the consent notice first, then answers. Betty cannot speak in a companion meeting yet, but when she heard her name and will answer, the companion plays her soft listening chime on your own computer (never into the call), when `meetings.listening_tone` and `meetings.voice_on_address` are on; the meeting's own voice setting does not apply. Saying "betty leave" ends the meeting, as does stopping the capture. The lines still waiting when the meeting ends ("Leaving now." among them) are served by the replies route after the end, until the window's cursor has passed them or two minutes are over.
- **After the meeting** it is an ordinary meeting: notes, research and the Inbox hand-off are unchanged.

| Route | |
|---|---|
| `GET /api/companion/info` | Consent notice and version, sample rate, channels, `max_chunk_bytes`. |
| `POST /api/companion/meetings` | `{title, app, host_name, consent_version, consent_attested: true}`; 201 with the meeting record. |
| `POST /api/companion/meetings/{id}/audio?channel=call\|mic&seq=N` | One PCM chunk; per channel in order from 0; 409 with `expected_seq` on a gap; a resend answers `duplicate: true`. |
| `GET /api/companion/meetings/{id}/replies?after=N` | Betty's lines after the cursor, `next_seq`, and the meeting `state`; after the meeting ended, its last unfetched lines once. |
| `GET /api/companion/meetings/{id}/replies?after=N` | Betty's lines after the cursor, `next_seq`, the meeting `state`, and `tone` (true once when the window should play the listening chime now; Quorum's `say.tone`); after the meeting ended, its last unfetched lines once. |
| `POST /api/companion/meetings/{id}/end` | Ends the meeting after transcribing buffered speech. |

The dashboard's ● Record ([Recording into the Inbox](inbox-recording.md)) stays the no-install option: it records a Chromium tab's audio and is transcribed after the recording ends, so Betty cannot answer during the call, and it cannot hear a desktop meeting app.
Expand Down Expand Up @@ -494,7 +494,7 @@ Every key has an environment override that wins over `hive.yaml`. The full list
| `meetings.tts_token_file` | `/data/secrets/meetings_tts_token` | Keystore-sealed TTS service token file. |
| `meetings.delivery` | `chat` | Where meeting output goes. |
| `meetings.voice_on_address` | `true` | Allow speaking when addressed in a voice-enabled meeting. |
| `meetings.listening_tone` | `true` | Betty plays a short, soft two-note chime when she heard her name in a spoken request and is about to answer, so the room knows she is listening (`HIVE_MEETINGS_LISTENING_TONE`). The only setting: no volume or sound options. It plays only when voice is on, never over speech, and is dropped silently if the audio path is busy. |
| `meetings.listening_tone` | `true` | Betty plays a short, soft two-note chime when she heard her name in a spoken request and is about to answer, so the room knows she is listening (`HIVE_MEETINGS_LISTENING_TONE`). The only setting: no volume or sound options. It plays only when voice is on (a companion meeting plays it in the companion on the host's computer instead), never over speech, and is dropped silently if the audio path is busy. |
| `meetings.bot_name` | the persona's display name | Bot display name; `hive (notes)` with the persona off. |
| `meetings.invite_policy` | `owner` | Who may send hive to a meeting. |
| `meetings.research_pool_size` | `2` | Research agents (`research-1..N`). |
Expand Down
39 changes: 24 additions & 15 deletions src/pkg/meetings/companion.go
Original file line number Diff line number Diff line change
Expand Up @@ -86,10 +86,21 @@ type CompanionLine struct {

// CompanionReplies is what the companion window polls: Betty's lines after
// a cursor and the meeting's state (so the window notices a "betty leave").
// Tone asks the window to play the listening chime now (say.tone; Quorum
// sets it once per tone and only while the window is polling).
type CompanionReplies struct {
Lines []CompanionLine `json:"lines"`
NextSeq int64 `json:"next_seq"`
State State `json:"state"`
Tone bool `json:"tone"`
}

// CompanionPage is Quorum's /companion/outbox answer: the lines after a
// cursor, the next cursor, and whether a listening tone is waiting.
type CompanionPage struct {
Lines []CompanionLine `json:"lines"`
NextSeq int64 `json:"next_seq"`
Tone bool `json:"tone"`
}

// ChunkGapError is an out-of-order chunk; Expected is the seq to send next.
Expand All @@ -115,7 +126,7 @@ var (
// Quorum fakes of other tests stay as they are.
type CompanionQuorum interface {
CompanionAudio(ctx context.Context, nativeID, channel string, seq int, pcm []byte) (CompanionChunk, error)
CompanionOutbox(ctx context.Context, nativeID string, after int64) ([]CompanionLine, int64, error)
CompanionOutbox(ctx context.Context, nativeID string, after int64) (CompanionPage, error)
}

// IsCompanionChannel reports whether ch is a companion audio channel.
Expand Down Expand Up @@ -220,14 +231,14 @@ func (m *Manager) CompanionReplies(ctx context.Context, id, user string, asOwner
if err != nil {
return CompanionReplies{}, err
}
lines, next, err := cq.CompanionOutbox(ctx, mt.NativeID, after)
page, err := cq.CompanionOutbox(ctx, mt.NativeID, after)
if err != nil {
return CompanionReplies{}, err
}
if lines != nil {
out.Lines = lines
if page.Lines != nil {
out.Lines = page.Lines
}
out.NextSeq = next
out.NextSeq, out.Tone = page.NextSeq, page.Tone
return out, nil
}

Expand Down Expand Up @@ -305,25 +316,23 @@ func (c *Client) CompanionAudio(ctx context.Context, nativeID, channel string, s
return out, nil
}

// CompanionOutbox reads Quorum's /companion/outbox after a cursor.
func (c *Client) CompanionOutbox(ctx context.Context, nativeID string, after int64) ([]CompanionLine, int64, error) {
// CompanionOutbox reads Quorum's /companion/outbox after a cursor. An
// older Quorum without the tone answers no "tone", which reads as false.
func (c *Client) CompanionOutbox(ctx context.Context, nativeID string, after int64) (CompanionPage, error) {
q := url.Values{"meeting_id": {nativeID}, "after": {strconv.FormatInt(max(after, 0), 10)}}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.base+"/companion/outbox?"+q.Encode(), nil)
if err != nil {
return nil, 0, err
return CompanionPage{}, err
}
body, err := c.companionDo(req, "companion/outbox")
if err != nil {
return nil, 0, err
}
var out struct {
Lines []CompanionLine `json:"lines"`
NextSeq int64 `json:"next_seq"`
return CompanionPage{}, err
}
var out CompanionPage
if err := json.Unmarshal(body, &out); err != nil {
return nil, 0, fmt.Errorf("quorum companion/outbox: %w", err)
return CompanionPage{}, fmt.Errorf("quorum companion/outbox: %w", err)
}
return out.Lines, out.NextSeq, nil
return out, nil
}

var _ CompanionQuorum = (*Client)(nil)
6 changes: 3 additions & 3 deletions src/pkg/meetings/companion_tail.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,12 @@ func (m *Manager) keepCompanionTail(ctx context.Context, mt Meeting) {
if err != nil {
return
}
lines, last, err := cq.CompanionOutbox(ctx, mt.NativeID, 0)
page, err := cq.CompanionOutbox(ctx, mt.NativeID, 0)
if err != nil {
m.log.Info("[meetings] companion: last lines not kept", "meeting", mt.ID, "error", err)
return
}
if len(lines) == 0 {
if len(page.Lines) == 0 {
return
}
now := m.opts.Now()
Expand All @@ -60,7 +60,7 @@ func (m *Manager) keepCompanionTail(ctx context.Context, mt Meeting) {
delete(m.tails.by, id)
}
}
m.tails.by[mt.ID] = companionTail{lines: lines, last: last, expires: now.Add(companionTailGrace)}
m.tails.by[mt.ID] = companionTail{lines: page.Lines, last: page.NextSeq, expires: now.Add(companionTailGrace)}
}

// companionTail returns an ended meeting's kept lines after the cursor and
Expand Down
37 changes: 24 additions & 13 deletions src/pkg/meetings/companion_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ type fakeCompanionQuorum struct {
chunks []string
audioErr error
lines []CompanionLine
tone bool
}

func (f *fakeCompanionQuorum) CompanionAudio(_ context.Context, nativeID, channel string, seq int, pcm []byte) (CompanionChunk, error) {
Expand All @@ -30,18 +31,18 @@ func (f *fakeCompanionQuorum) CompanionAudio(_ context.Context, nativeID, channe
return CompanionChunk{Seq: seq}, nil
}

func (f *fakeCompanionQuorum) CompanionOutbox(_ context.Context, _ string, after int64) ([]CompanionLine, int64, error) {
func (f *fakeCompanionQuorum) CompanionOutbox(_ context.Context, _ string, after int64) (CompanionPage, error) {
f.cmu.Lock()
defer f.cmu.Unlock()
var out []CompanionLine
next := after
out := CompanionPage{NextSeq: after, Tone: f.tone}
f.tone = false
for _, l := range f.lines {
if l.Seq > after {
out = append(out, l)
next = l.Seq
out.Lines = append(out.Lines, l)
out.NextSeq = l.Seq
}
}
return out, next, nil
return out, nil
}

func newCompanionFake() *fakeCompanionQuorum {
Expand Down Expand Up @@ -171,9 +172,19 @@ func TestCompanionAudioRepliesAndEnd(t *testing.T) {
if err != nil || len(r.Lines) != 1 || r.Lines[0].Text != "an answer" || r.NextSeq != 2 || r.State != StateLive {
t.Fatalf("replies = %+v, %v", r, err)
}
if r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 9); err != nil || r.Lines == nil || len(r.Lines) != 0 {
if r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 9); err != nil || r.Lines == nil || len(r.Lines) != 0 || r.Tone {
t.Fatalf("empty replies = %+v, %v", r, err)
}
// A listening tone Quorum holds for the window is passed through once.
q.cmu.Lock()
q.tone = true
q.cmu.Unlock()
if r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 2); err != nil || !r.Tone || len(r.Lines) != 0 {
t.Fatalf("replies with a tone = %+v, %v", r, err)
}
if r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 2); err != nil || r.Tone {
t.Fatalf("the tone is delivered once = %+v, %v", r, err)
}

ended, err := m.EndCompanion(ctx, mt.ID, "ana", false)
if err != nil || ended.State != StateEnded || ended.StateReason != ReasonCompanionEnded {
Expand Down Expand Up @@ -236,7 +247,7 @@ func TestClientCompanionRoutes(t *testing.T) {
_, _ = io.WriteString(w, `not json`)
default:
if r.URL.Path == "/companion/outbox" {
_, _ = io.WriteString(w, `{"lines":[{"seq":3,"text":"hi","at":"2026-11-16T12:00:00Z"}],"next_seq":3}`)
_, _ = io.WriteString(w, `{"lines":[{"seq":3,"text":"hi","at":"2026-11-16T12:00:00Z"}],"next_seq":3,"tone":true}`)
return
}
_, _ = io.WriteString(w, `{"seq":2,"duplicate":true}`)
Expand All @@ -253,9 +264,9 @@ func TestClientCompanionRoutes(t *testing.T) {
if gotAuth != "Bearer tok" || gotQuery != "channel=mic&meeting_id=m1&seq=2" || string(gotBody) != "\x01\x02" {
t.Fatalf("request: auth=%q query=%q body=%v", gotAuth, gotQuery, gotBody)
}
lines, next, err := c.CompanionOutbox(ctx, "m1", -5)
if err != nil || next != 3 || len(lines) != 1 || lines[0].Text != "hi" || gotQuery != "after=0&meeting_id=m1" {
t.Fatalf("outbox = %+v, %d, %v (query %q)", lines, next, err, gotQuery)
page, err := c.CompanionOutbox(ctx, "m1", -5)
if err != nil || page.NextSeq != 3 || len(page.Lines) != 1 || page.Lines[0].Text != "hi" || !page.Tone || gotQuery != "after=0&meeting_id=m1" {
t.Fatalf("outbox = %+v, %v (query %q)", page, err, gotQuery)
}

var gap *ChunkGapError
Expand All @@ -265,7 +276,7 @@ func TestClientCompanionRoutes(t *testing.T) {
if _, err := c.CompanionAudio(ctx, "ended", CompanionChannelCall, 0, nil); !errors.Is(err, ErrNotLive) {
t.Fatalf("ended = %v", err)
}
if _, _, err := c.CompanionOutbox(ctx, "missing", 0); !errors.Is(err, ErrNotFound) {
if _, err := c.CompanionOutbox(ctx, "missing", 0); !errors.Is(err, ErrNotFound) {
t.Fatalf("missing = %v", err)
}
if _, err := c.CompanionAudio(ctx, "bad", CompanionChannelCall, 0, nil); !IsCode(err, CodeInvalidArgument) {
Expand All @@ -277,7 +288,7 @@ func TestClientCompanionRoutes(t *testing.T) {
if _, err := c.CompanionAudio(ctx, "garbled", CompanionChannelCall, 0, nil); err == nil {
t.Fatal("garbled audio reply should fail")
}
if _, _, err := c.CompanionOutbox(ctx, "garbled", 0); err == nil {
if _, err := c.CompanionOutbox(ctx, "garbled", 0); err == nil {
t.Fatal("garbled outbox reply should fail")
}
srv.Close()
Expand Down
17 changes: 16 additions & 1 deletion src/pkg/meetings/live/tone.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ func (s *session) notePartial(who string) {
// voice (chat-only fallback plays nothing), speech already queued or
// playing, and someone else mid-sentence each stop it.
func (s *session) toneAllowed(asker string) (bool, string) {
if off, _ := s.voiceOff(); off != "" {
if off := s.toneVoiceOff(); off != "" {
return false, off
}
now := s.now()
Expand All @@ -56,6 +56,21 @@ func (s *session) toneAllowed(asker string) (bool, string) {
return true, ""
}

// toneVoiceOff is voiceOff for the tone. A companion meeting has no voice
// in the call at all: the desktop companion plays the chime on the host's
// own computer, never into the call, so the meeting's voice setting does
// not apply there and only meetings.voice_on_address does.
func (s *session) toneVoiceOff() string {
if m, err := s.r.opts.Meetings.Get(s.id); err == nil && m.Platform == meetings.PlatformCompanion {
if !s.r.opts.Policy.VoiceOnAddress {
return speakPolicyOff
}
return ""
}
off, _ := s.voiceOff()
return off
}

// playTone asks for the tone in the background. The answer never waits for
// it: the call runs on its own goroutine under meetings.ToneTimeout and its
// error is only logged.
Expand Down
18 changes: 18 additions & 0 deletions src/pkg/meetings/live/tone_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,24 @@ func TestToneNotPlayedWhenVoiceOff(t *testing.T) {
}
}

// A companion meeting has no voice in the call, yet its chime plays: the
// desktop companion plays it on the host's computer. voice_on_address off
// still refuses it.
func TestToneOnCompanionIgnoresMeetingVoice(t *testing.T) {
tm, s, _ := toneSession(t)
m := tm.m[s.id]
m.Platform, m.VoiceEnabled = meetings.PlatformCompanion, false
tm.m[s.id] = m
if ok, why := s.toneAllowed("Bo"); !ok {
t.Fatalf("companion tone refused: %q", why)
}
s.onPersonaReply(context.Background(), toneReply)
tm.eventually(t, 1)

s.r.opts.Policy.VoiceOnAddress = false
refused(t, s, "Bo", speakPolicyOff)
}

// She does not chime over her own speech or into someone else's sentence;
// the asker's own partial does not stop it.
func TestToneNotOverSpeechOrCrosstalk(t *testing.T) {
Expand Down
Loading