diff --git a/changelog.d/added-18396-meeting-attendee-settings.md b/changelog.d/added-18396-meeting-attendee-settings.md new file mode 100644 index 0000000000..ed680ce294 --- /dev/null +++ b/changelog.d/added-18396-meeting-attendee-settings.md @@ -0,0 +1 @@ +- **Settings, Meeting attendee.** A new Settings tab manages the hive's meeting persona: pick one of eleven presets built only from voices the self-hosted Kokoro TTS ships (Betty Bee by default, plus American and British English, Spanish, French, Italian, Brazilian Portuguese, Hindi, Japanese and Mandarin personas with intros in their own language) or edit the name, aliases, pronouns, voice type, language, accent, voice, humor and intro with a live preview and a Play sample button, set the unprompted-answer caps and voice-on-address, and see the attendee address `hive@` with the people who may invite her. Owner or read-write, through `GET`/`PUT /api/meetings/persona` and `POST /api/meetings/persona/sample`; the email controls are shown disabled until email-in lands ([#18396](https://github.com/hivecommons/hive/issues/18396)). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index 1d21434f40..73fad1a78e 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -978,6 +978,834 @@ } } }, + "/api/meetings/persona": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "Get the meeting attendee persona", + "description": "Settings, Meeting attendee: the effective persona, the presets, which fields are overridden (config or env), the Kokoro voices, whether a restart is required, and the attendee email section. Owner or read-write.", + "responses": { + "200": { + "description": "Meeting attendee settings", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "effective": { + "type": "object", + "description": "The resolved persona. Fields resolve as if the persona were on; enabled says whether it is.", + "properties": { + "enabled": { + "type": "boolean" + }, + "preset": { + "type": "string" + }, + "name": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "pronouns": { + "type": "string" + }, + "language": { + "type": "string" + }, + "voice": { + "type": "string" + }, + "voice_type": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "intro_template": { + "type": "string" + }, + "leave_phrases": { + "type": "array", + "items": { + "type": "string" + } + }, + "humor": { + "type": "string" + }, + "intro": { + "type": "string", + "description": "The rendered intro" + }, + "unprompted": { + "type": "object", + "properties": { + "per_10m": { + "type": "integer" + }, + "min_gap_s": { + "type": "integer" + }, + "per_meeting": { + "type": "integer" + }, + "answer_wait_s": { + "type": "integer" + }, + "min_confidence": { + "type": "number" + }, + "queue_depth": { + "type": "integer" + }, + "stale_s": { + "type": "integer" + } + } + }, + "voice_on_address": { + "type": "boolean" + } + } + }, + "presets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "pronouns": { + "type": "string" + }, + "language": { + "type": "string" + }, + "voice": { + "type": "string" + }, + "voice_type": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "humor": { + "type": "string" + }, + "intro_template": { + "type": "string" + }, + "plain_intro_template": { + "type": "string" + }, + "leave_phrases": { + "type": "array", + "items": { + "type": "string" + } + }, + "sample_line": { + "type": "string" + } + } + } + }, + "overridden": { + "type": "object", + "description": "meetings.persona keys not taken from the preset or defaults, mapped to config or env", + "additionalProperties": { + "type": "string" + } + }, + "voices": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "language": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "voice_type": { + "type": "string" + } + } + } + }, + "voice_types": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "available": { + "type": "boolean" + }, + "note": { + "type": "string" + } + } + } + }, + "restart_required": { + "type": "boolean" + }, + "running": { + "type": "boolean" + }, + "tts_configured": { + "type": "boolean" + }, + "email": { + "type": "object", + "description": "The Email section; available is false until email-in is enabled", + "properties": { + "available": { + "type": "boolean" + }, + "address": { + "type": "string", + "description": "hive@" + }, + "inviters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "login": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "role": { + "type": "string" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "proof": { + "type": "string", + "description": "verified or pending" + }, + "verified_at": { + "type": "string" + } + } + } + } + } + } + }, + "approvals": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "from": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "received_at": { + "type": "string" + } + } + } + }, + "calendar_invites": { + "type": "boolean" + }, + "mail_in_files": { + "type": "boolean" + }, + "error": { + "type": "string" + } + } + } + } + } + } + } + }, + "403": { + "description": "Owner or read-write access required" + }, + "503": { + "description": "Config is not available" + } + } + }, + "put": { + "tags": [ + "Meetings" + ], + "summary": "Save the meeting attendee persona", + "description": "Saves meetings.persona (and meetings.voice_on_address) to hive.yaml. An absent field is unchanged, an empty one (or 0 for a cap) clears the override, and a value equal to the preset's is stored as no override. Validated as if the persona were on. Owner or read-write. Audited as meetings_persona.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "preset": { + "type": "string" + }, + "clear_overrides": { + "type": "boolean", + "description": "Drop every field override first" + }, + "name": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "pronouns": { + "type": "string" + }, + "language": { + "type": "string" + }, + "voice": { + "type": "string" + }, + "voice_type": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "intro_template": { + "type": "string" + }, + "leave_phrases": { + "type": "array", + "items": { + "type": "string" + } + }, + "humor": { + "type": "string" + }, + "unprompted": { + "type": "object", + "properties": { + "per_10m": { + "type": "integer" + }, + "min_gap_s": { + "type": "integer" + }, + "per_meeting": { + "type": "integer" + }, + "answer_wait_s": { + "type": "integer" + }, + "min_confidence": { + "type": "number" + }, + "queue_depth": { + "type": "integer" + }, + "stale_s": { + "type": "integer" + } + } + }, + "voice_on_address": { + "type": "boolean" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Meeting attendee settings", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "effective": { + "type": "object", + "description": "The resolved persona. Fields resolve as if the persona were on; enabled says whether it is.", + "properties": { + "enabled": { + "type": "boolean" + }, + "preset": { + "type": "string" + }, + "name": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "pronouns": { + "type": "string" + }, + "language": { + "type": "string" + }, + "voice": { + "type": "string" + }, + "voice_type": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "intro_template": { + "type": "string" + }, + "leave_phrases": { + "type": "array", + "items": { + "type": "string" + } + }, + "humor": { + "type": "string" + }, + "intro": { + "type": "string", + "description": "The rendered intro" + }, + "unprompted": { + "type": "object", + "properties": { + "per_10m": { + "type": "integer" + }, + "min_gap_s": { + "type": "integer" + }, + "per_meeting": { + "type": "integer" + }, + "answer_wait_s": { + "type": "integer" + }, + "min_confidence": { + "type": "number" + }, + "queue_depth": { + "type": "integer" + }, + "stale_s": { + "type": "integer" + } + } + }, + "voice_on_address": { + "type": "boolean" + } + } + }, + "presets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "aliases": { + "type": "array", + "items": { + "type": "string" + } + }, + "pronouns": { + "type": "string" + }, + "language": { + "type": "string" + }, + "voice": { + "type": "string" + }, + "voice_type": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "humor": { + "type": "string" + }, + "intro_template": { + "type": "string" + }, + "plain_intro_template": { + "type": "string" + }, + "leave_phrases": { + "type": "array", + "items": { + "type": "string" + } + }, + "sample_line": { + "type": "string" + } + } + } + }, + "overridden": { + "type": "object", + "description": "meetings.persona keys not taken from the preset or defaults, mapped to config or env", + "additionalProperties": { + "type": "string" + } + }, + "voices": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "language": { + "type": "string" + }, + "accent": { + "type": "string" + }, + "voice_type": { + "type": "string" + } + } + } + }, + "voice_types": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "available": { + "type": "boolean" + }, + "note": { + "type": "string" + } + } + } + }, + "restart_required": { + "type": "boolean" + }, + "running": { + "type": "boolean" + }, + "tts_configured": { + "type": "boolean" + }, + "email": { + "type": "object", + "description": "The Email section; available is false until email-in is enabled", + "properties": { + "available": { + "type": "boolean" + }, + "address": { + "type": "string", + "description": "hive@" + }, + "inviters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "login": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "role": { + "type": "string" + }, + "emails": { + "type": "array", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "proof": { + "type": "string", + "description": "verified or pending" + }, + "verified_at": { + "type": "string" + } + } + } + } + } + } + }, + "approvals": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "from": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "received_at": { + "type": "string" + } + } + } + }, + "calendar_invites": { + "type": "boolean" + }, + "mail_in_files": { + "type": "boolean" + }, + "error": { + "type": "string" + } + } + } + } + } + } + } + }, + "400": { + "description": "Invalid persona" + }, + "403": { + "description": "Owner or read-write access required" + }, + "500": { + "description": "Saving the config failed" + }, + "503": { + "description": "Config is not available" + } + } + } + }, + "/api/meetings/persona/sample": { + "get": { + "tags": [ + "Meetings" + ], + "summary": "Play a persona sample (audio element)", + "description": "The same sample as POST, with voice, language, display_name and text as query parameters, so the dashboard's audio element can play it from the dashboard origin (the CSP has no media-src). Owner or read-write.", + "parameters": [ + { + "name": "voice", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "language", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "display_name", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "text", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The audio", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "Text too long" + }, + "403": { + "description": "Owner or read-write access required" + }, + "502": { + "description": "The TTS service failed" + }, + "503": { + "description": "TTS not configured, or config is not available" + } + } + }, + "post": { + "tags": [ + "Meetings" + ], + "summary": "Play a persona sample", + "description": "Speaks a short line through the meetings TTS service (Kokoro /v1/audio/speech) and returns the audio, at most 2 MiB. Optional unsaved voice, language and display name; text at most 200 characters, default the persona's sample line. Owner or read-write.", + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "voice": { + "type": "string" + }, + "language": { + "type": "string" + }, + "display_name": { + "type": "string" + }, + "text": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "The audio", + "content": { + "audio/mpeg": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "Invalid request or text too long" + }, + "403": { + "description": "Owner or read-write access required" + }, + "502": { + "description": "The TTS service failed" + }, + "503": { + "description": "TTS not configured, or config is not available" + } + } + } + }, "/api/integration-orchestration": { "get": { "tags": ["System"], diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index edbfa874be..c479b952ed 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,10 +24,10 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1776` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1777` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1778` | -| `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:551` | -| `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:552` | -| `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:553` | -| `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:554` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1779` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1780` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1781` | +| `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:552` | +| `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:553` | +| `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:554` | +| `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:555` | diff --git a/src/docs/api-reference/configuration.md b/src/docs/api-reference/configuration.md index 2f1fb3ebd4..2d79a5ecca 100644 --- a/src/docs/api-reference/configuration.md +++ b/src/docs/api-reference/configuration.md @@ -101,8 +101,8 @@ 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:522` | | `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:523` | -| `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)); always an array) and `write_kinds` | `pkg/dashboard/api.go:547` | -| `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:548` | +| `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)); always an array) and `write_kinds` | `pkg/dashboard/api.go:548` | +| `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:549` | | `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/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index 6847ccf131..357daa6a14 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -84,7 +84,7 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:377` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:378` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:379` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1783` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1786` | ### Activity observation provenance The CI snapshot retains real check/node IDs, head, App ID and transition times. diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index 573bcd31b8..73194e7845 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -24,17 +24,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)). Also `startedAt` (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say "Restarted" vs "Upgraded") and, until the first status is published, `startupPhase`/`startupPhaseLabel` (the boot phase a fresh pod is in) ([#15788](https://github.com/hivecommons/hive/issues/15788)) | `pkg/dashboard/api.go:45` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:46` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:70` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1756` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1757` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1758` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1764` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1769` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1770` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1771` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1772` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1773` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1774` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1775` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1759` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1760` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1761` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1767` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1772` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1773` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1774` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1775` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1776` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1777` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1778` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index 21a2399480..ea49660911 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -100,3 +100,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/meetings/schedule/{eid}/decline` | Owner only | Decline an event awaiting approval; later updates of the same invite stay declined. Audited as `meeting_schedule_decline` | `pkg/dashboard/api_meetings_schedule.go:86` | | `POST` | `/api/meetings/schedule/{eid}/cancel` | Owner only | Stop hive joining the event (every occurrence of a series); a meeting already live is not left. Audited as `meeting_schedule_cancel` | `pkg/dashboard/api_meetings_schedule.go:87` | | `POST` | `/api/meetings/schedule/{eid}/skip` | Owner only | Skip the next occurrence hive has not joined: a single meeting becomes `skipped`, a series moves on. Audited as `meeting_schedule_skip` | `pkg/dashboard/api_meetings_schedule.go:88` | +| `GET` | `/api/meetings/persona` | Owner or read-write | Settings, Meeting attendee: `{effective, presets, overridden, voices, voice_types, restart_required, running, tts_configured, email}`. `effective` is the resolved persona (fields resolved as if on, `enabled` separately) with the rendered `intro` and `voice_on_address`; `presets` lists the built-in personas, the default first; `overridden` maps each `meetings.persona` key not taken from the preset or defaults to `config` or `env`; `voices` are the Kokoro voices with language, accent and voice type; `restart_required` is true when the saved persona differs from the one the hive booted with; `email` is the attendee address (`hive@`), the access list with registered calendar emails and proof status, the approval queue and the email-in switches (`available: false` until email-in is enabled). See [Meeting attendee settings](../meetings.md#meeting-attendee-settings) | `pkg/dashboard/api_meetings_persona.go:163` | +| `PUT` | `/api/meetings/persona` | Owner or read-write | Save `meetings.persona` to `hive.yaml`: `{enabled?, preset?, clear_overrides?, name?, display_name?, aliases?, pronouns?, language?, voice?, voice_type?, accent?, intro_template?, leave_phrases?, humor?, unprompted?: {per_10m?, min_gap_s?, per_meeting?, answer_wait_s?, min_confidence?, queue_depth?, stale_s?}, voice_on_address?}`. An absent field is unchanged, an empty one (or 0 for a cap) clears the override, a value equal to the preset's is stored as no override, and `clear_overrides` drops every field override first. Validated as if the persona were on; returns the GET body. 400 invalid. Audited as `meetings_persona` | `pkg/dashboard/api_meetings_persona.go:164` | +| `POST` | `/api/meetings/persona/sample` | Owner or read-write | Speak a short line through the meetings TTS service (Kokoro `POST /v1/audio/speech`) and return the audio (`audio/mpeg`, at most 2 MiB, `Cache-Control: no-store`). Optional `{voice?, language?, display_name?, text?}` (unsaved form values; `text` at most 200 characters, default the persona's sample line in its language). 503 "TTS not configured" until `meetings.tts_url` is set, 400 invalid, 502 the TTS service failed | `pkg/dashboard/api_meetings_persona.go:165` | +| `GET` | `/api/meetings/persona/sample` | Owner or read-write | The same sample with `voice`, `language`, `display_name` and `text` as query parameters, for the dashboard's `