diff --git a/changelog.d/added-18596-meetings-desktop-companion.md b/changelog.d/added-18596-meetings-desktop-companion.md new file mode 100644 index 0000000000..1b1a57b417 --- /dev/null +++ b/changelog.d/added-18596-meetings-desktop-companion.md @@ -0,0 +1 @@ +- Meetings: desktop companion meetings (`/api/companion/*`): the companion app streams a person's own meeting client audio and microphone, after a versioned consent confirmation, as a live meeting Betty takes part in; her replies go to the companion window (#18596). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index ed80a0500b..9b92d16e57 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -90,6 +90,564 @@ } ], "paths": { + "/api/companion/info": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "Desktop companion settings", + "description": "Owner or read-write. What the desktop companion shows and sends before a capture: the consent notice and its version, the PCM sample rate, the channels and the chunk limit.", + "responses": { + "200": { + "description": "Companion settings", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "consent_version": { + "type": "string" + }, + "consent_text": { + "type": "string" + }, + "sample_rate": { + "type": "integer" + }, + "channels": { + "type": "array", + "items": { + "type": "string" + } + }, + "max_chunk_bytes": { + "type": "integer" + } + } + } + } + } + }, + "403": { + "description": "Not owner or read-write, or another person's companion meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Meetings or companion meetings are not enabled on this hive", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/api/companion/meetings": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "Start a desktop companion meeting", + "description": "Owner or read-write. Starts a live meeting fed by the desktop companion (the person's own meeting client audio and microphone). The request must name the current consent_version and confirm the participants were told (consent_attested). Who attested, when and the notice version are stored with the meeting.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "app": { + "type": "string" + }, + "host_name": { + "type": "string" + }, + "consent_version": { + "type": "string" + }, + "consent_attested": { + "type": "boolean" + } + }, + "required": [ + "consent_version", + "consent_attested" + ] + } + } + } + }, + "responses": { + "201": { + "description": "The meeting record", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "platform": { + "type": "string" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Consent not acknowledged or a field too long", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Not owner or read-write, or another person's companion meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Meetings or companion meetings are not enabled on this hive", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/api/companion/meetings/{id}/audio": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "Upload one companion audio chunk", + "description": "The companion meeting's starter (or an owner). The body is raw 16 kHz mono s16le PCM, at most max_chunk_bytes. Chunks are accepted in order per channel from seq 0; a gap answers 409 with expected_seq and a resend of a stored seq is acknowledged with duplicate: true.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting id from the start response" + }, + { + "name": "channel", + "in": "query", + "required": true, + "schema": { + "type": "string", + "enum": [ + "call", + "mic" + ] + }, + "description": "call = the meeting app's audio, mic = the person's microphone" + }, + { + "name": "seq", + "in": "query", + "required": true, + "schema": { + "type": "integer", + "minimum": 0 + }, + "description": "Chunk number per channel, from 0" + } + ], + "requestBody": { + "required": true, + "content": { + "application/octet-stream": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "responses": { + "200": { + "description": "Stored or recognised", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "seq": { + "type": "integer" + }, + "duplicate": { + "type": "boolean" + } + } + } + } + } + }, + "400": { + "description": "Bad channel, seq or sample count", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "No such meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "409": { + "description": "Out of order (expected_seq) or the meeting is not live", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + }, + "expected_seq": { + "type": "integer" + } + } + } + } + } + }, + "413": { + "description": "Chunk too large", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Not owner or read-write, or another person's companion meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Meetings or companion meetings are not enabled on this hive", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/api/companion/meetings/{id}/replies": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "Betty's lines for the companion window", + "description": "The companion meeting's starter (or an owner). Lines hive posted for the meeting (the consent notice first) after the cursor, and the meeting state so the window notices the meeting ended.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting id from the start response" + }, + { + "name": "after", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 0 + }, + "description": "Cursor: the next_seq of the previous call" + } + ], + "responses": { + "200": { + "description": "Lines and state", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "lines": { + "type": "array", + "items": { + "type": "object", + "properties": { + "seq": { + "type": "integer" + }, + "text": { + "type": "string" + }, + "at": { + "type": "string" + } + } + } + }, + "next_seq": { + "type": "integer" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Bad cursor", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "No such meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Not owner or read-write, or another person's companion meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Meetings or companion meetings are not enabled on this hive", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/api/companion/meetings/{id}/end": { + "post": { + "tags": [ + "Meetings" + ], + "summary": "End a companion meeting", + "description": "The companion meeting's starter (or an owner): the companion stopped capturing. Speech still buffered is transcribed first.", + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Meeting id from the start response" + } + ], + "responses": { + "200": { + "description": "The meeting record", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "No such meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "403": { + "description": "Not owner or read-write, or another person's companion meeting", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Meetings or companion meetings are not enabled on this hive", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, "/api/meetings/{id}/approve": { "post": { "tags": [ diff --git a/src/cmd/hive/meetings_companion.go b/src/cmd/hive/meetings_companion.go new file mode 100644 index 0000000000..952e1ceea1 --- /dev/null +++ b/src/cmd/hive/meetings_companion.go @@ -0,0 +1,89 @@ +package main + +import ( + "context" + "errors" + "fmt" + + "github.com/hivecommons/hive/pkg/dashboard" + "github.com/hivecommons/hive/pkg/meetings" +) + +// Companion side of meetingsDashboard (hivecommons/hive#18596): the desktop +// companion streams a person's own meeting client audio as a live meeting. + +// companionInfo is GET /api/companion/info. +type companionInfo struct { + ConsentVersion string `json:"consent_version"` + ConsentText string `json:"consent_text"` + SampleRate int `json:"sample_rate"` + Channels []string `json:"channels"` + MaxChunkBytes int `json:"max_chunk_bytes"` +} + +// companionDashboardError adds the companion errors to +// meetingsDashboardError. +func companionDashboardError(err error) error { + var gap *meetings.ChunkGapError + switch { + case err == nil: + return nil + case errors.As(err, &gap): + return &dashboard.CompanionGapError{Expected: gap.Expected} + case errors.Is(err, meetings.ErrCompanionNotYours): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingForbidden, err) + case errors.Is(err, meetings.ErrCompanionUnavailable): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingUnavailable, err) + case errors.Is(err, meetings.ErrNotCompanion): + return fmt.Errorf("%w: %v", dashboard.ErrMeetingInvalid, err) + default: + return meetingsDashboardError(err) + } +} + +func (d *meetingsDashboard) CompanionInfo() any { + return companionInfo{ + ConsentVersion: meetings.CompanionConsentVersion, + ConsentText: meetings.CompanionConsentText, + SampleRate: meetings.CompanionSampleRate, + Channels: []string{meetings.CompanionChannelCall, meetings.CompanionChannelMic}, + MaxChunkBytes: meetings.CompanionMaxChunkBytes, + } +} + +func (d *meetingsDashboard) StartCompanion(ctx context.Context, req dashboard.CompanionStartRequest, user string) (any, error) { + m, err := d.mgr.StartCompanion(ctx, meetings.CompanionStart{ + Title: req.Title, App: req.App, HostName: req.HostName, + ConsentVersion: req.ConsentVersion, Attested: req.ConsentAttested, User: user, + }) + if err != nil { + return nil, companionDashboardError(err) + } + return m, nil +} + +func (d *meetingsDashboard) CompanionAudio(ctx context.Context, id, user string, asOwner bool, channel string, seq int, pcm []byte) (any, error) { + res, err := d.mgr.CompanionAudio(ctx, id, user, asOwner, channel, seq, pcm) + if err != nil { + return nil, companionDashboardError(err) + } + return res, nil +} + +func (d *meetingsDashboard) CompanionReplies(ctx context.Context, id, user string, asOwner bool, after int64) (any, error) { + res, err := d.mgr.CompanionReplies(ctx, id, user, asOwner, after) + if err != nil { + return nil, companionDashboardError(err) + } + return res, nil +} + +func (d *meetingsDashboard) EndCompanion(ctx context.Context, id, user string, asOwner bool) (any, error) { + m, err := d.mgr.EndCompanion(ctx, id, user, asOwner) + if err != nil { + return nil, companionDashboardError(err) + } + return m, nil +} + +var _ dashboard.CompanionMeetingsService = (*meetingsDashboard)(nil) diff --git a/src/cmd/hive/meetings_companion_test.go b/src/cmd/hive/meetings_companion_test.go new file mode 100644 index 0000000000..3c2724001c --- /dev/null +++ b/src/cmd/hive/meetings_companion_test.go @@ -0,0 +1,113 @@ +package main + +import ( + "context" + "errors" + "testing" + + "github.com/hivecommons/hive/pkg/dashboard" + "github.com/hivecommons/hive/pkg/meetings" +) + +// companionStubQuorum is stubQuorum plus the companion routes; joins start +// live companion meetings. +type companionStubQuorum struct { + stubQuorum + gap bool +} + +func (q *companionStubQuorum) Join(context.Context, meetings.JoinArgs) (meetings.JoinResult, error) { + return meetings.JoinResult{MeetingID: "qc", Platform: meetings.PlatformCompanion, State: meetings.StateLive}, nil +} + +func (q *companionStubQuorum) CompanionAudio(_ context.Context, _, _ string, seq int, _ []byte) (meetings.CompanionChunk, error) { + if q.gap { + return meetings.CompanionChunk{}, &meetings.ChunkGapError{Expected: 2} + } + 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 TestMeetingsDashboardCompanion(t *testing.T) { + store, err := meetings.NewStore(t.TempDir()) + if err != nil { + t.Fatal(err) + } + q := &companionStubQuorum{stubQuorum: stubQuorum{events: make(chan meetings.Event, 8)}} + mgr, err := meetings.NewManager(meetings.Options{Store: store, Quorum: q, ConsentText: "consent"}) + if err != nil { + t.Fatal(err) + } + defer mgr.Close() + d := &meetingsDashboard{mgr: mgr} + ctx := context.Background() + + info, ok := d.CompanionInfo().(companionInfo) + if !ok || info.ConsentVersion != meetings.CompanionConsentVersion || info.SampleRate != meetings.CompanionSampleRate || len(info.Channels) != 2 { + t.Fatalf("info = %+v", d.CompanionInfo()) + } + if _, err := d.StartCompanion(ctx, dashboard.CompanionStartRequest{ConsentVersion: "old", ConsentAttested: true}, "ana"); !errors.Is(err, dashboard.ErrMeetingInvalid) { + t.Fatalf("old consent = %v", err) + } + v, err := d.StartCompanion(ctx, dashboard.CompanionStartRequest{ + Title: "Standup", App: "zoom", ConsentVersion: meetings.CompanionConsentVersion, ConsentAttested: true, + }, "ana") + if err != nil { + t.Fatal(err) + } + mt, ok := v.(meetings.Meeting) + if !ok || mt.Platform != meetings.PlatformCompanion { + t.Fatalf("start = %+v", v) + } + if _, err := d.CompanionAudio(ctx, mt.ID, "ana", false, "mic", 0, []byte{0, 0}); err != nil { + t.Fatal(err) + } + if _, err := d.CompanionAudio(ctx, mt.ID, "bob", false, "mic", 0, nil); !errors.Is(err, dashboard.ErrMeetingForbidden) { + t.Fatalf("other user = %v", err) + } + q.gap = true + var gap *dashboard.CompanionGapError + if _, err := d.CompanionAudio(ctx, mt.ID, "ana", false, "call", 5, nil); !errors.As(err, &gap) || gap.Expected != 2 { + t.Fatalf("gap = %v", err) + } + if r, err := d.CompanionReplies(ctx, mt.ID, "ana", false, 0); err != nil || r.(meetings.CompanionReplies).NextSeq != 1 { + t.Fatalf("replies = %+v, %v", r, err) + } + if _, err := d.CompanionReplies(ctx, "mtg-missing", "ana", false, 0); !errors.Is(err, dashboard.ErrMeetingNotFound) { + t.Fatalf("missing = %v", err) + } + if v, err := d.EndCompanion(ctx, mt.ID, "ana", false); err != nil || v.(meetings.Meeting).State != meetings.StateEnded { + t.Fatalf("end = %+v, %v", v, err) + } + if _, err := d.EndCompanion(ctx, "mtg-missing", "ana", false); !errors.Is(err, dashboard.ErrMeetingNotFound) { + t.Fatalf("end missing = %v", err) + } + + plain := &meetingsDashboard{mgr: companionTestManager(t, &stubQuorum{events: make(chan meetings.Event, 1)})} + if _, err := plain.StartCompanion(ctx, dashboard.CompanionStartRequest{ConsentVersion: meetings.CompanionConsentVersion, ConsentAttested: true}, "ana"); !errors.Is(err, dashboard.ErrMeetingUnavailable) { + t.Fatalf("no companion quorum = %v", err) + } + if err := companionDashboardError(meetings.ErrNotCompanion); !errors.Is(err, dashboard.ErrMeetingInvalid) { + t.Fatalf("not companion = %v", err) + } + if companionDashboardError(nil) != nil { + t.Fatal("nil error") + } +} + +func companionTestManager(t *testing.T, q meetings.Quorum) *meetings.Manager { + t.Helper() + store, err := meetings.NewStore(t.TempDir()) + if err != nil { + t.Fatal(err) + } + mgr, err := meetings.NewManager(meetings.Options{Store: store, Quorum: q, ConsentText: "consent"}) + if err != nil { + t.Fatal(err) + } + t.Cleanup(mgr.Close) + return mgr +} diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 8d753bd19e..d281c7eccf 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -27,7 +27,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1792` | | `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1793` | | `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1794` | -| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:558` | -| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:559` | -| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:560` | -| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:561` | +| `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:559` | +| `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:560` | +| `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:561` | +| `DELETE` | `/api/github-owner-identity` | Owner only | Disconnect: removes the token file, drops every write-tier reference repo to read-only on the next pass, returns the previous `login` and a `note` that GitHub-side revocation is done under Settings → Applications on github.com; audited as `github_owner_identity_disconnected` | `pkg/dashboard/api.go:562` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index 9cf22c7829..28f7cd81e6 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -101,11 +101,11 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PUT` | `/api/config/escalation` | Owner only | Escalation Config Set | `pkg/dashboard/api.go:215` | | `GET` | `/api/config/write-surface` | Owner only | Lane write allowlist (`write_surface.allowlist`, [#9587](https://github.com/hivecommons/hive/issues/9587)): `allowlist`, `ops`, `warnings` | `pkg/dashboard/api.go:524` | | `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:525` | -| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:552` | -| `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:553` | -| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:555` | -| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:564` | -| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:565` | +| `GET` | `/api/config/reference-repos` | Owner only | `project.reference_repos` ([#18136](https://github.com/hivecommons/hive/issues/18136)): `reference_repos` (`{repo, write, write_token_file}` plus `derived_from` on a derived entry and, on every write entry, `credential_state`, `credential_reason` and `credential_login`, the GitHub account the writes appear under ([#18197](https://github.com/hivecommons/hive/issues/18197)), plus `credential_identity` (`bot`, `owner` or `token_file`) and `credential_note`, the one-line why ([#18516](https://github.com/hivecommons/hive/issues/18516)); always an array), `write_kinds`, `write_identity` (`project.remote_write_identity` with the default applied), `write_identities` and `bot_login` (the App bot login, when known) | `pkg/dashboard/api.go:553` | +| `PUT` | `/api/config/reference-repos` | Owner only | Replace `project.reference_repos`; `{"reference_repos": []}` clears it. Refused with a 400 and nothing changed when the config loader would reject the list (bare name, repo also in `project.repos`, duplicate, unknown write kind, token file without write) or when a write entry has no credential boot would accept — the same message boot exits 22 with — or when an entry carries a `write_token_file` the config file does not already hold for that repo (the path is operator-only; a dashboard write opt-in writes as the hive owner's connected GitHub account). Entries with `derived_from` ([#18139](https://github.com/hivecommons/hive/issues/18139)) are the request issue's grant: echo them back as served; changing one's write set, leaving one out, sending one the hive did not derive or adding a hand-written entry for the same repo is a 409 naming the issue to change instead ([#18161](https://github.com/hivecommons/hive/issues/18161)). They are never stored: the saved list holds the hand-written entries and the derived set is merged back in memory after the save. 500 when the file could not be written (proxy restored, nothing changed). On success the GitHub proxy's reference policies are replaced without a restart; audited as `config_reference_repos` | `pkg/dashboard/api.go:554` | +| `PUT` | `/api/config/reference-repos/write-identity` | Owner only | Set `project.remote_write_identity` ([#18516](https://github.com/hivecommons/hive/issues/18516)): body `{"write_identity": "bot"}`, one of `bot`, `bot_only`, `owner`. 400 on an unknown value, or when a hand-written write entry would have no credential under the new value (the message boot exits 22 with); nothing is stored then. 500 when the file could not be written. On success the reference repos are re-resolved before the response, which is the same body as `GET /api/config/reference-repos`; audited as `config_remote_write_identity` with `previous` and `write_identity` | `pkg/dashboard/api.go:556` | +| `GET` | `/api/config/prompt-sources` | Owner only | Repo-sourced prompt and definition gate ([#18490](https://github.com/hivecommons/hive/issues/18490)): `repos` (one row per managed repo, then any owner approval whose repo is no longer managed, each `{repo, managed, owner_approved, seed_allowed, allowed, approved_by, approved_at}`), `seed_enabled`, `seed_allowlist`, `trust_notice`, `seed_only_note` | `pkg/dashboard/api.go:565` | +| `PUT` | `/api/config/prompt-sources/owner-repos` | Owner only | `{"repo": "org/name", "allowed": true, "acknowledge_trust": true}` approves one of the hive's managed repos as a `prompt_source` / `definition_source` repo; `"allowed": false` revokes. 400 with nothing changed for a repo outside `project.repos` (still needs the seed edit), a malformed slug, or an approval without `acknowledge_trust: true`. Persisted to `variables.security.owner_github_prompt_repos` in the running config; audited as `config_prompt_source_repo`. Responds with the GET body | `pkg/dashboard/api.go:566` | | `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:218` | | `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:221` | | `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:227` | diff --git a/src/docs/api-reference/packs-and-acmm.md b/src/docs/api-reference/packs-and-acmm.md index 05ffdb94d2..065ec666a1 100644 --- a/src/docs/api-reference/packs-and-acmm.md +++ b/src/docs/api-reference/packs-and-acmm.md @@ -25,7 +25,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/repos/{owner}/{repo}/items/{number}/decide-delegated/plan` | Same as `…/decide-delegated` | Preview for *Let hive decide*: runs the same owner-delegate policy with **no side effects** (nothing written, no job) and answers `{would, rule, acting, title, summary, why, consequences[], ladder, mergeable_as_is, alternatives[], writes: false, prior, notes}` — `summary` is one verb-first sentence with no "Hive would:" prefix (*Send #15332 back to its author with one instruction: make CI green, nothing else.*), `why` one short line (*CI is red.*), `consequences` at most two items, `ladder` the rung that decided with its `ruled_out` list, and `mergeable_as_is` whether an as-is merge is honest (the queue-merge and merge-now alternatives are dropped when it is not). The dialog shows **Cancel** / **Let hive do that**, plus **Approve and let hive merge** (or **Merge now as maintainer** when the hive would approve anyway) only when `mergeable_as_is`; only then does the SPA post `…/decide-delegated` with `chosen` naming the button. A transient GitHub failure (5xx, rate limit, timeout) is retried twice with backoff before the plan gives up. A failure answers `{ok: false, error, reason, retryable, attempts, elapsed_ms, hive, hint}` under **409** when the item is no longer open (`reason: not-open`) or **424** when a read it depends on failed (`github`), is not configured (`config`) or the plan itself failed (`plan`) — never 502/503, which the hosted Ingress intercepts and replaces with its generic *hive unavailable* page (hivecommons/hive#16776). See [dashboard-sections.md](../dashboard-sections.md#let-hive-decide). | `pkg/dashboard/api.go:341`, `pkg/dashboard/api_repo_item_decide_delegated_plan.go` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/recheck` | Same as `…/hold` (owner or repo write), signed-in GitHub user | *Re-check permissions* on an issue parked on a capability blocker (#15099): probes the GitHub App installation's permissions; when the missing permission is granted, clears every ledger entry blocked on it and un-parks the item (`{result: {outcome: "released", …}}`), otherwise `{result: {outcome: "no-effect", reason: "blocker", options: [...]}}`; 404 when the item has no blocker, 409 when the blocker is not a capability gap | `pkg/dashboard/api.go:342` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/blocker/close-partial` | Same as `…/hold` (owner or repo write), signed-in GitHub user | Option (c) on a capability blocker (#15099): labels the issue `hive/partially-addressed`, posts the operator's `{"comment"}` naming what remains and closes it; the ledger entry is cleared | `pkg/dashboard/api.go:343` | -| `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:550`, `pkg/dashboard/api_repo_item_accept_triage.go` | +| `POST` | `/api/repos/{owner}/{repo}/items/{number}/accept-triage` | Owner or repo write/maintain/admin | Accept triage on an issue from the activity monitor's row menu — what a maintainer accepting triage on GitHub does by hand: adds the reporter-trust triage label (`triage/accepted`, or the first of `issue_filter.reporter_trust.untrusted_require_labels`; the label is created in the repo if missing) and removes the awaiting label (`needs-triage` / `reporter_trust.awaiting_label`) and a Hive-written `stage/015-triage-needed`. Empty body. Returns `{ok, repo, number, acceptLabel, added, removed, alreadyAccepted, minStatusSeq}`; an issue already carrying the accept label with nothing left to remove is a no-op (`alreadyAccepted: true`, no write, no audit). 404 for a pull request or an unknown item. The status snapshot's labels are patched so the next reconcile reads 010 Actionable before the engine's own 015 → 010 derivation. Every write is audited as `repo_item_accept_triage` under the dashboard user. | `pkg/dashboard/api.go:551`, `pkg/dashboard/api_repo_item_accept_triage.go` | | `POST` | `/api/repos/{owner}/{repo}/items/{number}/sentinel-confirm` | Owner or repo write/maintain/admin | **Confirm safe** on the activity monitor's human-gate pill ([#17470](https://github.com/hivecommons/hive/issues/17470)): a person confirms a sentinel finding is intended. Body `{comment?, type?}` (`type` is `pr` or `issue`, comment ≤ 4000 characters). Posts the confirmation as a comment first — ``, `@user confirmed the sentinel finding safe from the dashboard.`, then the comment text — and removes every label matching the configured sentinel label (`sentinel.label`, default `sentinel-alert`, case-insensitive). Returns `{ok, repo, number, label, removed, alreadyClear, result}`; with no sentinel label on the item the comment is still posted and `alreadyClear` is true. 403 for a repository the hive does not watch. Audited as `repo_item_sentinel_confirm` under the dashboard user; the operator-action ledger records it as `confirm-sentinel`. | `pkg/dashboard/api.go:333`, `pkg/dashboard/api_repo_item_sentinel_confirm.go` | | `GET` | `/api/acmm/evaluation` | Dashboard auth/session | ACMMEvaluation — combined codebase + operational result, cached server-side for 1 hour (`acmmEvalTTL`). `?refresh=1` (the dashboard's "🔄 Re-evaluate" button, #5877) bypasses the hourly TTL but is debounced server-side: requests within 1 minute of the last evaluation (`acmmRefreshDebounce`) still serve the cache, since a full refresh costs up to ~29 GitHub GetContents calls per repo. The response's `last_evaluated_at` timestamp reports when the cached evaluation was computed | `pkg/dashboard/api.go:345`, `pkg/dashboard/api_acmm_eval.go` | | `POST` | `/api/acmm/issue` | Owner only | ACMMCreate Issue — files on GitHub or, with `governor.acmm.issue_tracker: work_source` / body `tracker: "work_source"` on a Linear-sourced hive, on Linear; response `tracker` says which. See [ACMM policy matrix](../acmm-policy-matrix.md#where-acmm-gap-issues-are-filed) | `pkg/dashboard/api.go:346` | diff --git a/src/docs/meetings.md b/src/docs/meetings.md index fb6e412eb1..5d15e8655e 100644 --- a/src/docs/meetings.md +++ b/src/docs/meetings.md @@ -147,6 +147,26 @@ If the meeting platform's chat is unavailable, hive cannot post the consent noti The same operations are available over the [meetings API](api-reference/knowledge.md) (`/api/meetings`). +## Desktop companion + +The desktop companion ([hivecommons/quorum-companion](https://github.com/hivecommons/quorum-companion), design in [#18596](https://github.com/hivecommons/hive/issues/18596)) lets Betty take part in a call the person is already in, through their **own** meeting app, without any bot joining the meeting. It is how Betty works on Zoom without a Zoom app: Zoom refuses automated web-client bots, and the companion does not try to get around that; it captures the person's own Zoom (or Teams, Meet, ...) audio on their own computer. + +- **Consent.** Before every capture the companion shows the companion consent notice (`GET /api/companion/info`, versioned) and the person confirms the participants were told and agreed. Zoom does not tell the other participants, so that confirmation is the consent gate. The meeting records who confirmed it, when, and the notice version (`companion` on the meeting record). The companion keeps a "Betty is listening" indicator on while it captures and offers the notice on the clipboard to paste into the meeting chat. +- **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. +- **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. +- **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`. | +| `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. + ## Calendar The **Calendar** section, right after **Inbox** in the left menu, lists the meetings hive is scheduled to join. The scheduler checks every 15 seconds (`HIVE_MEETINGS_SCHEDULE_TICK_S`) and sends hive in 60 seconds before each start (`HIVE_MEETINGS_SCHEDULE_LEAD_S`), the same way **Send hive to a meeting** does. A meeting without an end time is still joined up to 15 minutes after it starts; after that it is marked skipped as missed. diff --git a/src/pkg/dashboard/api.go b/src/pkg/dashboard/api.go index 7c141e90cb..deb209505e 100644 --- a/src/pkg/dashboard/api.go +++ b/src/pkg/dashboard/api.go @@ -539,6 +539,7 @@ func (s *Server) RegisterAPI(deps *Dependencies) { s.registerInboxRoutes() s.registerInboxRecordingRoutes() s.registerMeetingsRoutes() + s.registerCompanionRoutes() s.registerMeetingsScheduleRoutes() s.registerMeetingsPersonaRoutes() s.registerMeetingsModelRoutes() diff --git a/src/pkg/dashboard/api_meetings_companion.go b/src/pkg/dashboard/api_meetings_companion.go new file mode 100644 index 0000000000..a97c0bdbf7 --- /dev/null +++ b/src/pkg/dashboard/api_meetings_companion.go @@ -0,0 +1,216 @@ +package dashboard + +import ( + "context" + "errors" + "fmt" + "io" + "net/http" + "strconv" + "strings" +) + +// Desktop companion meetings (hivecommons/hive#18596). The companion app +// captures a person's own meeting client audio and microphone after a +// consent prompt and streams it here as a live meeting Betty takes part in. +// Every route needs an owner or read-write session; a companion meeting can +// be used only by the person who started it (owners may use any). The +// meetings feature arrives through MeetingsService; companion support is the +// optional CompanionMeetingsService on the same value. + +// CompanionStartRequest is POST /api/companion/meetings. +type CompanionStartRequest struct { + Title string `json:"title"` + App string `json:"app"` + HostName string `json:"host_name"` + ConsentVersion string `json:"consent_version"` + // ConsentAttested is the person's confirmation that the participants + // were told and agreed. + ConsentAttested bool `json:"consent_attested"` +} + +// CompanionMeetingsService is the companion side of the meetings feature. +type CompanionMeetingsService interface { + // CompanionInfo is what the companion needs before a capture: the + // consent notice and its version, the PCM format and the chunk limit. + CompanionInfo() any + StartCompanion(ctx context.Context, req CompanionStartRequest, user string) (any, error) + CompanionAudio(ctx context.Context, id, user string, asOwner bool, channel string, seq int, pcm []byte) (any, error) + CompanionReplies(ctx context.Context, id, user string, asOwner bool, after int64) (any, error) + EndCompanion(ctx context.Context, id, user string, asOwner bool) (any, error) +} + +// ErrMeetingForbidden is another person's companion meeting. +var ErrMeetingForbidden = errors.New("this companion meeting belongs to someone else") + +// ErrMeetingUnavailable means companion meetings cannot run on this hive. +var ErrMeetingUnavailable = errors.New("companion meetings are not available on this hive") + +// CompanionGapError is an out-of-order audio chunk. +type CompanionGapError struct{ Expected int } + +func (e *CompanionGapError) Error() string { + return fmt.Sprintf("chunk out of order; expected seq %d", e.Expected) +} + +// companionMaxChunkBytes bounds one audio chunk body read here; the +// meetings service applies the exact limit it reports in CompanionInfo. +const companionMaxChunkBytes = 131072 + +func (s *Server) registerCompanionRoutes() { + s.mux.HandleFunc("GET /api/companion/info", s.handleCompanionInfo) + s.mux.HandleFunc("POST /api/companion/meetings", s.handleCompanionStart) + s.mux.HandleFunc("POST /api/companion/meetings/{id}/audio", s.handleCompanionAudio) + s.mux.HandleFunc("GET /api/companion/meetings/{id}/replies", s.handleCompanionReplies) + s.mux.HandleFunc("POST /api/companion/meetings/{id}/end", s.handleCompanionEnd) +} + +// companionService admits owner or read-write and returns the companion +// side of the meetings feature, answering the error itself otherwise. +func (s *Server) companionService(w http.ResponseWriter, r *http.Request) (CompanionMeetingsService, bool) { + if !requireInboxPlaybackRole(w, r) { + return nil, false + } + svc, ok := s.meetingsService(w) + if !ok { + return nil, false + } + cs, ok := svc.(CompanionMeetingsService) + if !ok { + jsonError(w, ErrMeetingUnavailable.Error(), http.StatusServiceUnavailable) + return nil, false + } + return cs, true +} + +// requestIsOwner reports a verified owner. +func requestIsOwner(r *http.Request) bool { + return isOwnerRole(r.Header.Get("X-Hive-Role")) && r.Header.Get(ownerRoleVerifiedHeader) == "true" +} + +func (s *Server) companionError(w http.ResponseWriter, r *http.Request, err error) { + var gap *CompanionGapError + switch { + case errors.As(err, &gap): + expected := gap.Expected + jsonStatusResponse(w, http.StatusConflict, inboxRecordingError{Error: err.Error(), ExpectedSeq: &expected}) + case errors.Is(err, ErrMeetingForbidden): + jsonError(w, err.Error(), http.StatusForbidden) + case errors.Is(err, ErrMeetingUnavailable): + jsonError(w, err.Error(), http.StatusServiceUnavailable) + default: + s.meetingsError(w, r, err) + } +} + +func (s *Server) handleCompanionInfo(w http.ResponseWriter, r *http.Request) { + cs, ok := s.companionService(w, r) + if !ok { + return + } + w.Header().Set("Cache-Control", "no-store") + jsonResponse(w, cs.CompanionInfo()) +} + +func (s *Server) handleCompanionStart(w http.ResponseWriter, r *http.Request) { + cs, ok := s.companionService(w, r) + if !ok { + return + } + var req CompanionStartRequest + if err := decodeBody(r, &req); err != nil { + jsonError(w, "invalid request body", http.StatusBadRequest) + return + } + req.Title, req.App, req.HostName = sanitizeString(req.Title), sanitizeString(req.App), sanitizeString(req.HostName) + ctx, cancel := context.WithTimeout(r.Context(), meetingsCallTimeout) + defer cancel() + m, err := cs.StartCompanion(ctx, req, requestUser(r)) + if err != nil { + s.companionError(w, r, err) + return + } + s.auditFromRequest(r, "meeting_companion_start", auditDetail("app", req.App, "consent_version", req.ConsentVersion), "") + w.Header().Set("Cache-Control", "no-store") + jsonStatusResponse(w, http.StatusCreated, m) +} + +// handleCompanionAudio stores chunk ?channel=call|mic&seq=N: the body is +// raw 16 kHz mono s16le PCM. Chunks are accepted in order per channel; a +// gap answers 409 with expected_seq and a resend is acknowledged again. +func (s *Server) handleCompanionAudio(w http.ResponseWriter, r *http.Request) { + cs, ok := s.companionService(w, r) + if !ok { + return + } + defer closeHTTPBody(r.Body) + channel := r.URL.Query().Get("channel") + seq, err := strconv.Atoi(r.URL.Query().Get("seq")) + if err != nil || seq < 0 { + jsonError(w, "seq must be a non-negative integer", http.StatusBadRequest) + return + } + data, err := io.ReadAll(http.MaxBytesReader(w, r.Body, companionMaxChunkBytes)) + if err != nil { + var tooBig *http.MaxBytesError + if errors.As(err, &tooBig) { + jsonError(w, fmt.Sprintf("a chunk must be at most %d bytes", companionMaxChunkBytes), http.StatusRequestEntityTooLarge) + return + } + jsonError(w, "reading chunk: "+err.Error(), http.StatusBadRequest) + return + } + ctx, cancel := context.WithTimeout(r.Context(), meetingsCallTimeout) + defer cancel() + res, err := cs.CompanionAudio(ctx, strings.TrimSpace(r.PathValue("id")), requestUser(r), requestIsOwner(r), channel, seq, data) + if err != nil { + s.companionError(w, r, err) + return + } + w.Header().Set("Cache-Control", "no-store") + jsonResponse(w, res) +} + +// handleCompanionReplies returns Betty's lines after ?after=N and the +// meeting's state. +func (s *Server) handleCompanionReplies(w http.ResponseWriter, r *http.Request) { + cs, ok := s.companionService(w, r) + if !ok { + return + } + var after int64 + if raw := r.URL.Query().Get("after"); raw != "" { + n, err := strconv.ParseInt(raw, 10, 64) + if err != nil || n < 0 { + jsonError(w, "after must be a non-negative integer", http.StatusBadRequest) + return + } + after = n + } + ctx, cancel := context.WithTimeout(r.Context(), meetingsCallTimeout) + defer cancel() + res, err := cs.CompanionReplies(ctx, strings.TrimSpace(r.PathValue("id")), requestUser(r), requestIsOwner(r), after) + if err != nil { + s.companionError(w, r, err) + return + } + w.Header().Set("Cache-Control", "no-store") + jsonResponse(w, res) +} + +func (s *Server) handleCompanionEnd(w http.ResponseWriter, r *http.Request) { + cs, ok := s.companionService(w, r) + if !ok { + return + } + id := strings.TrimSpace(r.PathValue("id")) + ctx, cancel := context.WithTimeout(r.Context(), meetingsCallTimeout) + defer cancel() + m, err := cs.EndCompanion(ctx, id, requestUser(r), requestIsOwner(r)) + if err != nil { + s.companionError(w, r, err) + return + } + s.auditFromRequest(r, "meeting_companion_end", auditDetail("meeting", id), "") + jsonResponse(w, m) +} diff --git a/src/pkg/dashboard/api_meetings_companion_test.go b/src/pkg/dashboard/api_meetings_companion_test.go new file mode 100644 index 0000000000..93decd92a7 --- /dev/null +++ b/src/pkg/dashboard/api_meetings_companion_test.go @@ -0,0 +1,193 @@ +package dashboard + +import ( + "context" + "encoding/json" + "errors" + "net/http" + "net/http/httptest" + "strings" + "sync" + "testing" +) + +// fakeCompanionService is the meetings fake plus the companion side. +type fakeCompanionService struct { + fakeMeetingsService + cmu sync.Mutex + cerr error + starts []CompanionStartRequest + startUser string + audio []string + owner bool + after int64 +} + +func (f *fakeCompanionService) CompanionInfo() any { + return map[string]any{"consent_version": "companion-test", "sample_rate": 16000} +} + +func (f *fakeCompanionService) StartCompanion(_ context.Context, req CompanionStartRequest, user string) (any, error) { + f.cmu.Lock() + defer f.cmu.Unlock() + f.starts, f.startUser = append(f.starts, req), user + if f.cerr != nil { + return nil, f.cerr + } + return map[string]any{"id": "mtg-c1", "platform": "companion", "state": "live"}, nil +} + +func (f *fakeCompanionService) CompanionAudio(_ context.Context, id, user string, asOwner bool, channel string, seq int, pcm []byte) (any, error) { + f.cmu.Lock() + defer f.cmu.Unlock() + f.audio = append(f.audio, id+"/"+user+"/"+channel+"/"+string(rune('0'+seq))+"/"+string(pcm)) + f.owner = asOwner + if f.cerr != nil { + return nil, f.cerr + } + return map[string]any{"seq": seq, "duplicate": false}, nil +} + +func (f *fakeCompanionService) CompanionReplies(_ context.Context, _, _ string, _ bool, after int64) (any, error) { + f.cmu.Lock() + defer f.cmu.Unlock() + f.after = after + if f.cerr != nil { + return nil, f.cerr + } + return map[string]any{"lines": []any{}, "next_seq": after, "state": "live"}, nil +} + +func (f *fakeCompanionService) EndCompanion(_ context.Context, id, _ string, _ bool) (any, error) { + if f.cerr != nil { + return nil, f.cerr + } + return map[string]any{"id": id, "state": "ended"}, nil +} + +func companionRequest(s *Server, method, path, body, role string, verified bool) *httptest.ResponseRecorder { + rec := httptest.NewRecorder() + req := httptest.NewRequest(method, path, strings.NewReader(body)) + req.Header.Set("X-Hive-User", "ana") + if role != "" { + req.Header.Set("X-Hive-Role", role) + } + if verified { + req.Header.Set(ownerRoleVerifiedHeader, "true") + } + s.mux.ServeHTTP(rec, req) + return rec +} + +func TestCompanionRoutesNeedOwnerOrReadWriteAndTheFeature(t *testing.T) { + s, _ := apiServer(t) + if rec := companionRequest(s, http.MethodGet, "/api/companion/info", "", "read-write", false); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("no meetings = %d", rec.Code) + } + s.SetMeetingsService(&fakeMeetingsService{}) + if rec := companionRequest(s, http.MethodGet, "/api/companion/info", "", "read-write", false); rec.Code != http.StatusServiceUnavailable { + t.Fatalf("meetings without companion = %d", rec.Code) + } + s.SetMeetingsService(&fakeCompanionService{}) + for _, tc := range []struct{ method, path string }{ + {http.MethodGet, "/api/companion/info"}, + {http.MethodPost, "/api/companion/meetings"}, + {http.MethodPost, "/api/companion/meetings/mtg-c1/audio?channel=mic&seq=0"}, + {http.MethodGet, "/api/companion/meetings/mtg-c1/replies"}, + {http.MethodPost, "/api/companion/meetings/mtg-c1/end"}, + } { + if rec := companionRequest(s, tc.method, tc.path, "{}", "read", false); rec.Code != http.StatusForbidden { + t.Errorf("%s %s as read = %d", tc.method, tc.path, rec.Code) + } + if rec := companionRequest(s, tc.method, tc.path, "{}", "owner", false); rec.Code != http.StatusForbidden { + t.Errorf("%s %s as unverified owner = %d", tc.method, tc.path, rec.Code) + } + } + if rec := companionRequest(s, http.MethodGet, "/api/companion/info", "", "read-write", false); rec.Code != http.StatusOK || !strings.Contains(rec.Body.String(), "companion-test") { + t.Fatalf("info = %d %s", rec.Code, rec.Body.String()) + } +} + +func TestCompanionStartAudioRepliesEnd(t *testing.T) { + s, _ := apiServer(t) + f := &fakeCompanionService{} + s.SetMeetingsService(f) + + rec := companionRequest(s, http.MethodPost, "/api/companion/meetings", + `{"title":"Standup x","app":"zoom","host_name":"Ana","consent_version":"v1","consent_attested":true}`, "read-write", false) + if rec.Code != http.StatusCreated { + t.Fatalf("start = %d %s", rec.Code, rec.Body.String()) + } + if len(f.starts) != 1 || f.starts[0].Title != "Standup x" || !f.starts[0].ConsentAttested || f.startUser != "ana" { + t.Fatalf("start request = %+v by %q", f.starts, f.startUser) + } + if rec := companionRequest(s, http.MethodPost, "/api/companion/meetings", "not json", "read-write", false); rec.Code != http.StatusBadRequest { + t.Fatalf("bad body = %d", rec.Code) + } + + if rec := companionRequest(s, http.MethodPost, "/api/companion/meetings/mtg-c1/audio?channel=mic&seq=3", "pcm", "owner", true); rec.Code != http.StatusOK { + t.Fatalf("audio = %d %s", rec.Code, rec.Body.String()) + } + if f.audio[0] != "mtg-c1/ana/mic/3/pcm" || !f.owner { + t.Fatalf("audio call = %v owner=%v", f.audio, f.owner) + } + for _, q := range []string{"channel=mic", "channel=mic&seq=-1", "channel=mic&seq=x"} { + if rec := companionRequest(s, http.MethodPost, "/api/companion/meetings/mtg-c1/audio?"+q, "", "read-write", false); rec.Code != http.StatusBadRequest { + t.Errorf("audio %q = %d", q, rec.Code) + } + } + big := strings.Repeat("a", companionMaxChunkBytes+1) + if rec := companionRequest(s, http.MethodPost, "/api/companion/meetings/mtg-c1/audio?channel=mic&seq=0", big, "read-write", false); rec.Code != http.StatusRequestEntityTooLarge { + t.Fatalf("big chunk = %d", rec.Code) + } + + if rec := companionRequest(s, http.MethodGet, "/api/companion/meetings/mtg-c1/replies?after=7", "", "read-write", false); rec.Code != http.StatusOK || f.after != 7 { + t.Fatalf("replies = %d after=%d", rec.Code, f.after) + } + if rec := companionRequest(s, http.MethodGet, "/api/companion/meetings/mtg-c1/replies?after=-2", "", "read-write", false); rec.Code != http.StatusBadRequest { + t.Fatalf("bad after = %d", rec.Code) + } + if rec := companionRequest(s, http.MethodPost, "/api/companion/meetings/mtg-c1/end", "", "read-write", false); rec.Code != http.StatusOK { + t.Fatalf("end = %d", rec.Code) + } +} + +func TestCompanionErrorsMapToStatuses(t *testing.T) { + s, _ := apiServer(t) + f := &fakeCompanionService{} + s.SetMeetingsService(f) + for _, tc := range []struct { + err error + code int + }{ + {&CompanionGapError{Expected: 4}, http.StatusConflict}, + {ErrMeetingForbidden, http.StatusForbidden}, + {ErrMeetingUnavailable, http.StatusServiceUnavailable}, + {ErrMeetingNotFound, http.StatusNotFound}, + {ErrMeetingInvalid, http.StatusBadRequest}, + {ErrMeetingConflict, http.StatusConflict}, + {errors.New("quorum down"), http.StatusBadGateway}, + } { + f.cerr = tc.err + for _, call := range []struct{ method, path string }{ + {http.MethodPost, "/api/companion/meetings"}, + {http.MethodPost, "/api/companion/meetings/mtg-c1/audio?channel=call&seq=1"}, + {http.MethodGet, "/api/companion/meetings/mtg-c1/replies"}, + {http.MethodPost, "/api/companion/meetings/mtg-c1/end"}, + } { + body := "{}" + rec := companionRequest(s, call.method, call.path, body, "read-write", false) + if rec.Code != tc.code { + t.Errorf("%v on %s = %d, want %d", tc.err, call.path, rec.Code, tc.code) + } + } + } + f.cerr = &CompanionGapError{Expected: 4} + rec := companionRequest(s, http.MethodPost, "/api/companion/meetings/mtg-c1/audio?channel=call&seq=9", "", "read-write", false) + var body struct { + ExpectedSeq int `json:"expected_seq"` + } + if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil || body.ExpectedSeq != 4 { + t.Fatalf("gap body = %s (%v)", rec.Body.String(), err) + } +} diff --git a/src/pkg/meetings/client.go b/src/pkg/meetings/client.go index c651a875e0..d284220106 100644 --- a/src/pkg/meetings/client.go +++ b/src/pkg/meetings/client.go @@ -293,6 +293,8 @@ type JoinArgs struct { // VoiceID is the TTS voice the bot speaks with (Discord's Kokoro voice, // Vexa's per-speak voice). Empty uses Quorum's default. VoiceID string `json:"voice_id,omitempty"` + // HostName names the companion's mic channel speaker. + HostName string `json:"host_name,omitempty"` } // JoinResult is meeting.join's result. diff --git a/src/pkg/meetings/companion.go b/src/pkg/meetings/companion.go new file mode 100644 index 0000000000..381be8ad42 --- /dev/null +++ b/src/pkg/meetings/companion.go @@ -0,0 +1,326 @@ +package meetings + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/url" + "strconv" + "strings" + "time" +) + +// Desktop companion meetings (hivecommons/hive#18596, quorum +// docs/contract.md "Companion audio"). A desktop app on a person's own +// computer captures their meeting client's audio (channel "call") and their +// microphone ("mic") after they accepted the companion consent prompt, and +// hive relays the PCM to Quorum. Nothing joins the meeting itself. Betty's +// chat lines go to an outbox the companion window reads. + +const ( + // CompanionConsentVersion names the consent notice the companion shows + // before every capture; a start must acknowledge exactly this version. + // Bump it whenever CompanionConsentText changes. + CompanionConsentVersion = "companion-2026-11-16" + // CompanionConsentText is the notice the companion shows (and offers to + // copy into the meeting chat) before it captures anything. + CompanionConsentText = "Betty, the hive's meeting assistant, will listen to this call through your own meeting app and microphone. " + + "The audio goes only to your hive, which transcribes it, takes notes and answers questions. " + + "The other participants are not told by the meeting app: tell them before you start, and only continue if everyone agrees. " + + "Recording consent laws differ by place." + // CompanionChannelCall is the meeting client's audio (everyone else). + CompanionChannelCall = "call" + // CompanionChannelMic is the person's own microphone. + CompanionChannelMic = "mic" + // CompanionSampleRate is the PCM rate the companion sends (16-bit mono). + CompanionSampleRate = 16000 + // CompanionMaxChunkBytes is the largest audio chunk hive accepts; it + // matches Quorum's QUORUM_COMPANION_MAX_CHUNK_BYTES default (4 s). + CompanionMaxChunkBytes = 131072 + // companionTitleMax bounds a companion meeting title. + companionTitleMax = 200 + // companionNameMax bounds the app and host names. + companionNameMax = 100 + // maxCompanionReplyBytes bounds one outbox response from Quorum. + maxCompanionReplyBytes = 1 << 20 +) + +// CompanionInfo is what hive records about a companion meeting's consent. +type CompanionInfo struct { + // App is the meeting app the companion captured ("zoom", "teams", ...). + App string `json:"app,omitempty"` + ConsentVersion string `json:"consent_version"` + AttestedBy string `json:"attested_by"` + AttestedAt time.Time `json:"attested_at"` +} + +// CompanionStart starts a companion meeting. +type CompanionStart struct { + Title string + App string + HostName string + // ConsentVersion must equal CompanionConsentVersion and Attested must + // be true: the person confirmed the participants were told. + ConsentVersion string + Attested bool + // User is the hive user starting it (the meeting's InvitedBy). + User string +} + +// CompanionChunk is Quorum's answer to one audio chunk. +type CompanionChunk struct { + Seq int `json:"seq"` + Duplicate bool `json:"duplicate"` +} + +// CompanionLine is one line for the companion window. +type CompanionLine struct { + Seq int64 `json:"seq"` + Text string `json:"text"` + At string `json:"at"` +} + +// 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"). +type CompanionReplies struct { + Lines []CompanionLine `json:"lines"` + NextSeq int64 `json:"next_seq"` + State State `json:"state"` +} + +// ChunkGapError is an out-of-order chunk; Expected is the seq to send next. +type ChunkGapError struct{ Expected int } + +func (e *ChunkGapError) Error() string { + return fmt.Sprintf("meetings: chunk out of order; expected seq %d", e.Expected) +} + +var ( + // ErrCompanionUnavailable: this hive's Quorum client cannot relay + // companion audio. + ErrCompanionUnavailable = errors.New("meetings: companion audio is not available") + // ErrCompanionNotYours: the meeting is another person's companion + // meeting (only its starter, or an owner, may use it). + ErrCompanionNotYours = errors.New("meetings: this companion meeting belongs to someone else") + // ErrNotCompanion: the meeting is not a companion meeting. + ErrNotCompanion = errors.New("meetings: not a companion meeting") +) + +// CompanionQuorum is the part of the Quorum client companion meetings use. +// *Client implements it; the manager checks for it at run time so the +// 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) +} + +// IsCompanionChannel reports whether ch is a companion audio channel. +func IsCompanionChannel(ch string) bool { + return ch == CompanionChannelCall || ch == CompanionChannelMic +} + +func (m *Manager) companionQuorum() (CompanionQuorum, error) { + cq, ok := m.opts.Quorum.(CompanionQuorum) + if !ok { + return nil, ErrCompanionUnavailable + } + return cq, nil +} + +// StartCompanion starts a companion meeting for req.User. It refuses a +// start without the current consent notice acknowledged and attested. +func (m *Manager) StartCompanion(ctx context.Context, req CompanionStart) (Meeting, error) { + if _, err := m.companionQuorum(); err != nil { + return Meeting{}, err + } + if !req.Attested || req.ConsentVersion != CompanionConsentVersion { + return Meeting{}, fmt.Errorf("%w: acknowledge the current companion consent notice (%s) and confirm the participants were told", + ErrInvalidRequest, CompanionConsentVersion) + } + user := strings.TrimSpace(req.User) + if user == "" { + return Meeting{}, fmt.Errorf("%w: a signed-in user is required", ErrInvalidRequest) + } + title := strings.TrimSpace(req.Title) + app := strings.ToLower(strings.TrimSpace(req.App)) + host := strings.TrimSpace(req.HostName) + if len(title) > companionTitleMax || len(app) > companionNameMax || len(host) > companionNameMax { + return Meeting{}, fmt.Errorf("%w: title is at most %d characters, app and host_name at most %d", + ErrInvalidRequest, companionTitleMax, companionNameMax) + } + if host == "" { + host = user + } + now := m.opts.Now() + mt := Meeting{ + ID: newMeetingID(), Platform: PlatformCompanion, Title: title, InvitedBy: user, State: StateRequested, + Companion: &CompanionInfo{App: app, ConsentVersion: req.ConsentVersion, AttestedBy: user, AttestedAt: now}, + CreatedAt: now, UpdatedAt: now, + } + return m.start(ctx, mt, JoinArgs{Platform: PlatformCompanion, DisplayName: m.opts.BotName, HostName: host}) +} + +// companionMeeting loads a companion meeting user may use. +func (m *Manager) companionMeeting(id, user string, asOwner bool) (Meeting, error) { + mt, err := m.opts.Store.Get(id) + if err != nil { + return Meeting{}, err + } + if mt.Platform != PlatformCompanion { + return Meeting{}, ErrNotCompanion + } + if !asOwner && mt.InvitedBy != strings.TrimSpace(user) { + return Meeting{}, ErrCompanionNotYours + } + return mt, nil +} + +// CompanionAudio relays chunk seq of one channel to Quorum. +func (m *Manager) CompanionAudio(ctx context.Context, id, user string, asOwner bool, channel string, seq int, pcm []byte) (CompanionChunk, error) { + if !IsCompanionChannel(channel) || seq < 0 { + return CompanionChunk{}, fmt.Errorf("%w: channel must be call or mic and seq non-negative", ErrInvalidRequest) + } + if len(pcm) > CompanionMaxChunkBytes || len(pcm)%2 != 0 { + return CompanionChunk{}, fmt.Errorf("%w: a chunk is whole 16-bit samples, at most %d bytes", ErrInvalidRequest, CompanionMaxChunkBytes) + } + mt, err := m.companionMeeting(id, user, asOwner) + if err != nil { + return CompanionChunk{}, err + } + if mt.State != StateLive { + return CompanionChunk{}, ErrNotLive + } + cq, err := m.companionQuorum() + if err != nil { + return CompanionChunk{}, err + } + return cq.CompanionAudio(ctx, mt.NativeID, channel, seq, pcm) +} + +// CompanionReplies returns Betty's lines for the companion window after +// the cursor. A meeting that is no longer live answers no lines and its +// state, so the window can close. +func (m *Manager) CompanionReplies(ctx context.Context, id, user string, asOwner bool, after int64) (CompanionReplies, error) { + mt, err := m.companionMeeting(id, user, asOwner) + if err != nil { + return CompanionReplies{}, err + } + out := CompanionReplies{Lines: []CompanionLine{}, NextSeq: max(after, 0), State: mt.State} + if mt.State != StateLive { + return out, nil + } + cq, err := m.companionQuorum() + if err != nil { + return CompanionReplies{}, err + } + lines, next, err := cq.CompanionOutbox(ctx, mt.NativeID, after) + if err != nil { + return CompanionReplies{}, err + } + if lines != nil { + out.Lines = lines + } + out.NextSeq = next + return out, nil +} + +// EndCompanion ends a companion meeting (the person stopped capturing). +func (m *Manager) EndCompanion(ctx context.Context, id, user string, asOwner bool) (Meeting, error) { + if _, err := m.companionMeeting(id, user, asOwner); err != nil { + return Meeting{}, err + } + return m.Leave(ctx, id, ReasonCompanionEnded) +} + +// ReasonCompanionEnded is the state reason when the companion stopped. +const ReasonCompanionEnded = "companion_ended" + +// quorumHTTPError is a non-2xx answer from a companion route. +type quorumHTTPError struct { + Error string `json:"error"` + Code string `json:"code"` + ExpectedSeq *int `json:"expected_seq"` +} + +// companionStatusError maps a companion route's error answer to the +// manager's errors. +func companionStatusError(route string, status int, body []byte) error { + var e quorumHTTPError + _ = json.Unmarshal(body, &e) + switch { + case status == http.StatusConflict && e.ExpectedSeq != nil: + return &ChunkGapError{Expected: *e.ExpectedSeq} + case status == http.StatusConflict: + return fmt.Errorf("%w: %s", ErrNotLive, e.Error) + case status == http.StatusNotFound: + return fmt.Errorf("%w: %s", ErrNotFound, e.Error) + case status == http.StatusBadRequest || status == http.StatusRequestEntityTooLarge: + return &ToolError{Tool: route, Code: CodeInvalidArgument, Message: e.Error} + default: + return fmt.Errorf("quorum %s: HTTP %d", route, status) + } +} + +// companionDo sends one companion request and reads a bounded body. +func (c *Client) companionDo(req *http.Request, route string) ([]byte, error) { + req.Header.Set("Authorization", "Bearer "+c.token) + resp, err := c.http.Do(req) + if err != nil { + return nil, fmt.Errorf("quorum %s: %w", route, err) + } + defer resp.Body.Close() + body, err := io.ReadAll(io.LimitReader(resp.Body, maxCompanionReplyBytes)) + if err != nil { + return nil, fmt.Errorf("quorum %s: %w", route, err) + } + if resp.StatusCode != http.StatusOK { + return nil, companionStatusError(route, resp.StatusCode, body) + } + return body, nil +} + +// CompanionAudio posts one PCM chunk to Quorum's /companion/audio. +func (c *Client) CompanionAudio(ctx context.Context, nativeID, channel string, seq int, pcm []byte) (CompanionChunk, error) { + q := url.Values{"meeting_id": {nativeID}, "channel": {channel}, "seq": {strconv.Itoa(seq)}} + req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.base+"/companion/audio?"+q.Encode(), bytes.NewReader(pcm)) + if err != nil { + return CompanionChunk{}, err + } + req.Header.Set("Content-Type", "application/octet-stream") + body, err := c.companionDo(req, "companion/audio") + if err != nil { + return CompanionChunk{}, err + } + var out CompanionChunk + if err := json.Unmarshal(body, &out); err != nil { + return CompanionChunk{}, fmt.Errorf("quorum companion/audio: %w", err) + } + 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) { + 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 + } + 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"` + } + if err := json.Unmarshal(body, &out); err != nil { + return nil, 0, fmt.Errorf("quorum companion/outbox: %w", err) + } + return out.Lines, out.NextSeq, nil +} + +var _ CompanionQuorum = (*Client)(nil) diff --git a/src/pkg/meetings/companion_test.go b/src/pkg/meetings/companion_test.go new file mode 100644 index 0000000000..59361ef702 --- /dev/null +++ b/src/pkg/meetings/companion_test.go @@ -0,0 +1,289 @@ +package meetings + +import ( + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "sync" + "testing" + "time" +) + +// fakeCompanionQuorum adds the companion routes to fakeQuorum. +type fakeCompanionQuorum struct { + *fakeQuorum + cmu sync.Mutex + chunks []string + audioErr error + lines []CompanionLine +} + +func (f *fakeCompanionQuorum) CompanionAudio(_ context.Context, nativeID, channel string, seq int, pcm []byte) (CompanionChunk, error) { + f.cmu.Lock() + defer f.cmu.Unlock() + if f.audioErr != nil { + return CompanionChunk{}, f.audioErr + } + f.chunks = append(f.chunks, nativeID+"/"+channel) + return CompanionChunk{Seq: seq}, nil +} + +func (f *fakeCompanionQuorum) CompanionOutbox(_ context.Context, _ string, after int64) ([]CompanionLine, int64, error) { + f.cmu.Lock() + defer f.cmu.Unlock() + var out []CompanionLine + next := after + for _, l := range f.lines { + if l.Seq > after { + out = append(out, l) + next = l.Seq + } + } + return out, next, nil +} + +func newCompanionFake() *fakeCompanionQuorum { + q := newFakeQuorum() + q.joinRes = JoinResult{MeetingID: "qc1", Platform: PlatformCompanion, State: StateLive} + return &fakeCompanionQuorum{fakeQuorum: q} +} + +func validStart() CompanionStart { + return CompanionStart{Title: "Standup", App: "Zoom", ConsentVersion: CompanionConsentVersion, Attested: true, User: "ana"} +} + +func waitConsent(t *testing.T, m *Manager, id string) Meeting { + t.Helper() + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + mt, err := m.Get(id) + if err == nil && mt.ConsentPostedAt != nil { + return mt + } + time.Sleep(5 * time.Millisecond) + } + t.Fatal("consent notice never posted") + return Meeting{} +} + +func TestStartCompanionRecordsConsentAndPostsTheNoticeToTheOutbox(t *testing.T) { + q := newCompanionFake() + m := newTestManager(t, q, time.Minute) + mt, err := m.StartCompanion(context.Background(), validStart()) + if err != nil { + t.Fatal(err) + } + if mt.Platform != PlatformCompanion || mt.State != StateLive || mt.NativeID != "qc1" || mt.InvitedBy != "ana" { + t.Fatalf("meeting = %+v", mt) + } + if mt.Companion == nil || mt.Companion.App != "zoom" || mt.Companion.ConsentVersion != CompanionConsentVersion || mt.Companion.AttestedBy != "ana" { + t.Fatalf("companion info = %+v", mt.Companion) + } + q.mu.Lock() + join := q.joins[0] + q.mu.Unlock() + if join.Platform != PlatformCompanion || join.HostName != "ana" || join.URL != "" || join.Voice { + t.Fatalf("join args = %+v", join) + } + q.stream("qc1") <- Event{Type: EventState, MeetingID: "qc1", State: StateLive} + waitConsent(t, m, mt.ID) + if posts, _ := q.snapshot(); len(posts) == 0 || posts[0] != testConsent { + t.Fatalf("posts = %v", posts) + } +} + +func TestStartCompanionRefusals(t *testing.T) { + m := newTestManager(t, newCompanionFake(), time.Minute) + ctx := context.Background() + for name, mut := range map[string]func(*CompanionStart){ + "not attested": func(r *CompanionStart) { r.Attested = false }, + "old notice": func(r *CompanionStart) { r.ConsentVersion = "companion-1999" }, + "no user": func(r *CompanionStart) { r.User = " " }, + "long title": func(r *CompanionStart) { r.Title = string(make([]byte, companionTitleMax+1)) }, + "long app name": func(r *CompanionStart) { r.App = string(make([]byte, companionNameMax+1)) }, + } { + req := validStart() + mut(&req) + if _, err := m.StartCompanion(ctx, req); !errors.Is(err, ErrInvalidRequest) { + t.Errorf("%s: err = %v", name, err) + } + } + plain := newTestManager(t, newFakeQuorum(), time.Minute) + if _, err := plain.StartCompanion(ctx, validStart()); !errors.Is(err, ErrCompanionUnavailable) { + t.Fatalf("no companion quorum: %v", err) + } + q := newCompanionFake() + q.joinErr = &ToolError{Tool: "meeting.join", Code: CodePlatformUnavailable, Message: "no transcription"} + failing := newTestManager(t, q, time.Minute) + mt, err := failing.StartCompanion(ctx, validStart()) + if !IsCode(err, CodePlatformUnavailable) || mt.State != StateFailed { + t.Fatalf("refused join = %+v, %v", mt, err) + } +} + +func TestCompanionAudioRepliesAndEnd(t *testing.T) { + q := newCompanionFake() + m := newTestManager(t, q, time.Minute) + ctx := context.Background() + mt, err := m.StartCompanion(ctx, validStart()) + if err != nil { + t.Fatal(err) + } + if _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelCall, 0, make([]byte, 640)); err != nil { + t.Fatal(err) + } + if _, err := m.CompanionAudio(ctx, mt.ID, "bob", false, CompanionChannelMic, 0, nil); !errors.Is(err, ErrCompanionNotYours) { + t.Fatalf("other user = %v", err) + } + if _, err := m.CompanionAudio(ctx, mt.ID, "owner", true, CompanionChannelMic, 0, nil); err != nil { + t.Fatalf("owner = %v", err) + } + for name, call := range map[string]func() error{ + "bad channel": func() error { _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, "video", 0, nil); return err }, + "negative": func() error { + _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelMic, -1, nil) + return err + }, + "odd bytes": func() error { + _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelMic, 1, []byte{1}) + return err + }, + "too big": func() error { + _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelMic, 1, make([]byte, CompanionMaxChunkBytes+2)) + return err + }, + } { + if err := call(); !errors.Is(err, ErrInvalidRequest) { + t.Errorf("%s: err = %v", name, err) + } + } + q.chunks = nil + q.audioErr = &ChunkGapError{Expected: 3} + var gap *ChunkGapError + if _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelCall, 5, nil); !errors.As(err, &gap) || gap.Expected != 3 { + t.Fatalf("gap = %v", err) + } + + q.lines = []CompanionLine{{Seq: 1, Text: "consent"}, {Seq: 2, Text: "an answer"}} + r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 1) + 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 { + t.Fatalf("empty replies = %+v, %v", r, err) + } + + ended, err := m.EndCompanion(ctx, mt.ID, "ana", false) + if err != nil || ended.State != StateEnded || ended.StateReason != ReasonCompanionEnded { + t.Fatalf("end = %+v, %v", ended, err) + } + if r, err := m.CompanionReplies(ctx, mt.ID, "ana", false, 0); err != nil || r.State != StateEnded || len(r.Lines) != 0 { + t.Fatalf("replies after end = %+v, %v", r, err) + } + if _, err := m.CompanionAudio(ctx, mt.ID, "ana", false, CompanionChannelCall, 0, nil); !errors.Is(err, ErrNotLive) { + t.Fatalf("audio after end = %v", err) + } + if _, err := m.EndCompanion(ctx, "mtg-missing", "ana", false); !errors.Is(err, ErrNotFound) { + t.Fatalf("missing = %v", err) + } +} + +func TestCompanionRoutesRefuseOtherMeetings(t *testing.T) { + q := newCompanionFake() + q.joinRes = JoinResult{MeetingID: "q-meet", Platform: PlatformGoogleMeet, State: StateJoining} + m := newTestManager(t, q, time.Minute) + mt, err := m.Join(context.Background(), JoinRequest{URL: "https://meet.google.com/abc-defg-hij"}) + if err != nil { + t.Fatal(err) + } + if _, err := m.CompanionReplies(context.Background(), mt.ID, "ana", true, 0); !errors.Is(err, ErrNotCompanion) { + t.Fatalf("meet meeting = %v", err) + } + if _, err := m.Join(context.Background(), JoinRequest{Platform: PlatformCompanion}); !errors.Is(err, ErrInvalidRequest) { + t.Fatalf("companion through Join = %v", err) + } +} + +func TestClientCompanionRoutes(t *testing.T) { + var gotAuth, gotQuery string + var gotBody []byte + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + gotAuth, gotQuery = r.Header.Get("Authorization"), r.URL.RawQuery + gotBody, _ = io.ReadAll(r.Body) + w.Header().Set("Content-Type", "application/json") + switch r.URL.Query().Get("meeting_id") { + case "gap": + w.WriteHeader(http.StatusConflict) + _, _ = io.WriteString(w, `{"error":"out of order","expected_seq":4}`) + case "ended": + w.WriteHeader(http.StatusConflict) + _, _ = io.WriteString(w, `{"error":"not live","code":"not_live"}`) + case "missing": + w.WriteHeader(http.StatusNotFound) + _, _ = io.WriteString(w, `{"error":"no meeting"}`) + case "bad": + w.WriteHeader(http.StatusRequestEntityTooLarge) + _, _ = io.WriteString(w, `{"error":"too large"}`) + case "boom": + w.WriteHeader(http.StatusInternalServerError) + case "garbled": + _, _ = 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}`) + return + } + _, _ = io.WriteString(w, `{"seq":2,"duplicate":true}`) + } + })) + defer srv.Close() + c := NewClient(srv.URL, "tok", nil) + ctx := context.Background() + + res, err := c.CompanionAudio(ctx, "m1", CompanionChannelMic, 2, []byte{1, 2}) + if err != nil || res.Seq != 2 || !res.Duplicate { + t.Fatalf("audio = %+v, %v", res, err) + } + 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) + } + + var gap *ChunkGapError + if _, err := c.CompanionAudio(ctx, "gap", CompanionChannelCall, 9, nil); !errors.As(err, &gap) || gap.Expected != 4 || gap.Error() == "" { + t.Fatalf("gap = %v", err) + } + 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) { + t.Fatalf("missing = %v", err) + } + if _, err := c.CompanionAudio(ctx, "bad", CompanionChannelCall, 0, nil); !IsCode(err, CodeInvalidArgument) { + t.Fatalf("too large = %v", err) + } + if _, err := c.CompanionAudio(ctx, "boom", CompanionChannelCall, 0, nil); err == nil { + t.Fatal("500 should fail") + } + 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 { + t.Fatal("garbled outbox reply should fail") + } + srv.Close() + if _, err := c.CompanionAudio(ctx, "m1", CompanionChannelCall, 0, nil); err == nil { + t.Fatal("closed server should fail") + } +} + +func TestIsCompanionChannel(t *testing.T) { + if !IsCompanionChannel("call") || !IsCompanionChannel("mic") || IsCompanionChannel("") { + t.Fatal("channel check") + } +} diff --git a/src/pkg/meetings/manager.go b/src/pkg/meetings/manager.go index 817af31d2b..b14efd4b6f 100644 --- a/src/pkg/meetings/manager.go +++ b/src/pkg/meetings/manager.go @@ -314,13 +314,21 @@ func (m *Manager) Join(ctx context.Context, req JoinRequest) (Meeting, error) { Title: strings.TrimSpace(req.Title), InvitedBy: req.InvitedBy, State: StateRequested, VoiceEnabled: req.Voice, VoiceCapable: voice, CreatedAt: now, UpdatedAt: now, } - if err := m.opts.Store.Save(mt); err != nil { - return Meeting{}, err - } - res, err := m.opts.Quorum.Join(ctx, JoinArgs{ + return m.start(ctx, mt, JoinArgs{ URL: req.URL, DisplayName: m.opts.BotName, Platform: req.Platform, GuildID: req.GuildID, ChannelID: req.ChannelID, Voice: voice, VoiceID: strings.TrimSpace(m.opts.VoiceID), }) +} + +// start stores a new meeting, calls meeting.join with args and starts +// following its events. A refused join leaves the meeting failed (or +// blocked) and returns the error. +func (m *Manager) start(ctx context.Context, mt Meeting, args JoinArgs) (Meeting, error) { + now := mt.CreatedAt + if err := m.opts.Store.Save(mt); err != nil { + return Meeting{}, err + } + res, err := m.opts.Quorum.Join(ctx, args) if err != nil { mt.State, mt.StateReason = StateFailed, err.Error() if IsCode(err, CodeBlocked) { diff --git a/src/pkg/meetings/meeting.go b/src/pkg/meetings/meeting.go index a2ca66fbf1..486f04a898 100644 --- a/src/pkg/meetings/meeting.go +++ b/src/pkg/meetings/meeting.go @@ -54,6 +54,9 @@ const ( PlatformTeams = "teams" PlatformZoom = "zoom" PlatformDiscord = "discord" + // PlatformCompanion is the desktop companion: a person's own meeting + // client audio, captured on their computer and relayed by hive. + PlatformCompanion = "companion" ) // Meeting is one meeting hive was sent to. @@ -86,6 +89,9 @@ type Meeting struct { // the line in the meeting chat) or "voice" (spoken because chat could // not deliver it). ConsentVia string `json:"consent_via,omitempty"` + // Companion is set on a desktop companion meeting: who attested that + // the participants were told, when, and which notice they saw. + Companion *CompanionInfo `json:"companion,omitempty"` // PreConsentDropped counts the lines (segments, drafts and chat) hive // discarded because they came before the consent notice was delivered. // Only the count is kept, never the content.