From 27dae84962bb2def4e2e9129d33d75c5e26f1454 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Sun, 15 Nov 2026 22:16:45 -0500 Subject: [PATCH 01/72] =?UTF-8?q?=F0=9F=90=9B=20changelog:=20recover=2014?= =?UTF-8?q?=20fragments=20stranded=20in=20src/changelog.d=20and=20fail=20t?= =?UTF-8?q?he=20release=20on=20strays=20(#18360)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🐛 changelog: recover 14 fragments stranded in src/changelog.d and fail the release on strays Fourteen fragments from PRs merged 2026-10-20..27 were written under src/changelog.d/, which compile-changelog.sh never reads, so their entries never reached CHANGELOG.md. Move them to the repo-root changelog.d/ (one needed the required '- ' bullet prefix) so the next release carries them, following the #11928 / #12675 precedent. Add a release-time backstop: compile-changelog.sh now fails loudly while any fragment other than README.md sits in src/changelog.d/ next to the changelog, so a stray that slips past the PR guard turns the next release job red instead of vanishing. Tests cover the README-only, stray-only and mixed cases plus a repo invariant that src/changelog.d/ holds only its README. Spell out the ../changelog.d/ path for agents working inside src/ in AGENTS.md, both READMEs and the scoped knowledge entry. Fixes #18264 Signed-off-by: Andy Anderson * 🐛 changelog: re-pin TRUSTED_SCRIPTS_TREE for the src/scripts change Signed-off-by: Andy Anderson --------- Signed-off-by: Andy Anderson Co-authored-by: hivecommons-hive[bot] <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- .github/scripts/integration-governance.cjs | 2 +- AGENTS.md | 2 +- changelog.d/README.md | 4 +- .../added-activity-monitor-accept-triage.md | 0 .../added-live-run-line.md | 0 .../added-merge-issue-author-credit.md | 0 .../added-tracker-sentinel-lane-text.md | 0 .../changed-crux-cmd-hive-runtime-seam.md | 0 .../changed-crux-runtime-seam.md | 0 .../changed-reviewer-l3-l4-packs.md | 0 .../fixed-13817-watchdog-producing-cadence.md | 0 .../fixed-13818-ci-gate-held-twin-runs.md | 0 changelog.d/fixed-18264-stranded-fragments.md | 1 + .../fixed-adopted-pr-rebase.md | 0 .../fixed-contributor-claim-starvation.md | 0 .../fixed-cost-per-agent-copilot-sessions.md | 0 .../fixed-supersession-sweep-stage-machine.md | 1 + .../fixed-upgrade-drain-visible-to-hub.md | 0 src/changelog.d/README.md | 4 +- .../fixed-supersession-sweep-stage-machine.md | 1 - .../changelog-fragment-exemptions.md | 2 +- src/scripts/compile-changelog.sh | 28 +++++++++++ src/scripts/test-compile-changelog.sh | 48 +++++++++++++++++++ 23 files changed, 87 insertions(+), 6 deletions(-) rename {src/changelog.d => changelog.d}/added-activity-monitor-accept-triage.md (100%) rename {src/changelog.d => changelog.d}/added-live-run-line.md (100%) rename {src/changelog.d => changelog.d}/added-merge-issue-author-credit.md (100%) rename {src/changelog.d => changelog.d}/added-tracker-sentinel-lane-text.md (100%) rename {src/changelog.d => changelog.d}/changed-crux-cmd-hive-runtime-seam.md (100%) rename {src/changelog.d => changelog.d}/changed-crux-runtime-seam.md (100%) rename {src/changelog.d => changelog.d}/changed-reviewer-l3-l4-packs.md (100%) rename {src/changelog.d => changelog.d}/fixed-13817-watchdog-producing-cadence.md (100%) rename {src/changelog.d => changelog.d}/fixed-13818-ci-gate-held-twin-runs.md (100%) create mode 100644 changelog.d/fixed-18264-stranded-fragments.md rename {src/changelog.d => changelog.d}/fixed-adopted-pr-rebase.md (100%) rename {src/changelog.d => changelog.d}/fixed-contributor-claim-starvation.md (100%) rename {src/changelog.d => changelog.d}/fixed-cost-per-agent-copilot-sessions.md (100%) create mode 100644 changelog.d/fixed-supersession-sweep-stage-machine.md rename {src/changelog.d => changelog.d}/fixed-upgrade-drain-visible-to-hub.md (100%) delete mode 100644 src/changelog.d/fixed-supersession-sweep-stage-machine.md diff --git a/.github/scripts/integration-governance.cjs b/.github/scripts/integration-governance.cjs index 8cb60d4461..f1521dbb76 100644 --- a/.github/scripts/integration-governance.cjs +++ b/.github/scripts/integration-governance.cjs @@ -9,7 +9,7 @@ const MAX_COMMITS = 1000; const MAX_AUTHOR_BATCH = 50; // This literal is inside the enrolled .github closure. A caller-supplied // preparedBy.sourceSHA must never choose a new executable verifier tree. -const TRUSTED_SCRIPTS_TREE = '630082873462479b5777ebc7d5dc255bae6f8df2'; +const TRUSTED_SCRIPTS_TREE = 'b60380f8d0040628eba73ad17c108b1be87c7fdd'; const SOURCE = 'https://github.com/kubernetes-sigs/kubebuilder-release-tools/tree/012269a88fa4c034a0acf1ba84c26b195c0dbab4'; const sha = value => crypto.createHash('sha256').update(value).digest('hex'); const git = (args, cwd = process.cwd()) => diff --git a/AGENTS.md b/AGENTS.md index d779d8f607..ea14d18778 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ These rules apply to every AI agent (hive agents, Copilot CLI, Claude Code, Code - Keep changes surgical and PR-sized; one concern per PR. - Sign commits (`git commit -s`); PR titles start with an emoji (`✨` feature, `🐛` fix, `📖` docs or proposal, `🌱` chore, `⚠️` breaking); `📝` fails the PR Type gate. -- Every PR with a user-visible `src/` code change needs a `changelog.d/-.md` fragment at the repository root whose body is a single `- ` bullet. +- Every PR with a user-visible `src/` code change needs a `changelog.d/-.md` fragment at the repository root whose body is a single `- ` bullet. From inside `src/` (the Go module) that path is `../changelog.d/`; anything written to `src/changelog.d/` is never compiled into `CHANGELOG.md`, fails the guard, and fails the release (#18264). - Do not hand-edit `src/docs` file:line citations; when CI's citation guard reports drift, run `python3 src/scripts/check-docs-citations.py --fix`. ## Project knowledge is scoped, not global diff --git a/changelog.d/README.md b/changelog.d/README.md index 01e1f28adf..1a91e00bbe 100644 --- a/changelog.d/README.md +++ b/changelog.d/README.md @@ -12,7 +12,9 @@ deleting the fragments in the same release commit. - **Location:** this directory, at the repository root. Never `src/changelog.d/`: the compiler does not read it, and the guard rejects fragments there with - the `git mv` that fixes it (#11919). + the `git mv` that fixes it (#11919). When working from `src/`, write + `../changelog.d/.md`. If a stray ever slips past the guard, the release + compile fails until it is moved here (#18264). - **Filename:** `-.md`, where `` is one of `added`, `changed`, `deprecated`, `fixed`, `security` — it picks the `###` diff --git a/src/changelog.d/added-activity-monitor-accept-triage.md b/changelog.d/added-activity-monitor-accept-triage.md similarity index 100% rename from src/changelog.d/added-activity-monitor-accept-triage.md rename to changelog.d/added-activity-monitor-accept-triage.md diff --git a/src/changelog.d/added-live-run-line.md b/changelog.d/added-live-run-line.md similarity index 100% rename from src/changelog.d/added-live-run-line.md rename to changelog.d/added-live-run-line.md diff --git a/src/changelog.d/added-merge-issue-author-credit.md b/changelog.d/added-merge-issue-author-credit.md similarity index 100% rename from src/changelog.d/added-merge-issue-author-credit.md rename to changelog.d/added-merge-issue-author-credit.md diff --git a/src/changelog.d/added-tracker-sentinel-lane-text.md b/changelog.d/added-tracker-sentinel-lane-text.md similarity index 100% rename from src/changelog.d/added-tracker-sentinel-lane-text.md rename to changelog.d/added-tracker-sentinel-lane-text.md diff --git a/src/changelog.d/changed-crux-cmd-hive-runtime-seam.md b/changelog.d/changed-crux-cmd-hive-runtime-seam.md similarity index 100% rename from src/changelog.d/changed-crux-cmd-hive-runtime-seam.md rename to changelog.d/changed-crux-cmd-hive-runtime-seam.md diff --git a/src/changelog.d/changed-crux-runtime-seam.md b/changelog.d/changed-crux-runtime-seam.md similarity index 100% rename from src/changelog.d/changed-crux-runtime-seam.md rename to changelog.d/changed-crux-runtime-seam.md diff --git a/src/changelog.d/changed-reviewer-l3-l4-packs.md b/changelog.d/changed-reviewer-l3-l4-packs.md similarity index 100% rename from src/changelog.d/changed-reviewer-l3-l4-packs.md rename to changelog.d/changed-reviewer-l3-l4-packs.md diff --git a/src/changelog.d/fixed-13817-watchdog-producing-cadence.md b/changelog.d/fixed-13817-watchdog-producing-cadence.md similarity index 100% rename from src/changelog.d/fixed-13817-watchdog-producing-cadence.md rename to changelog.d/fixed-13817-watchdog-producing-cadence.md diff --git a/src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md b/changelog.d/fixed-13818-ci-gate-held-twin-runs.md similarity index 100% rename from src/changelog.d/fixed-13818-ci-gate-held-twin-runs.md rename to changelog.d/fixed-13818-ci-gate-held-twin-runs.md diff --git a/changelog.d/fixed-18264-stranded-fragments.md b/changelog.d/fixed-18264-stranded-fragments.md new file mode 100644 index 0000000000..18fb3a16e0 --- /dev/null +++ b/changelog.d/fixed-18264-stranded-fragments.md @@ -0,0 +1 @@ +- Release: 14 changelog entries from late-October PRs (#13280, #13486, #13609, #13758, #13760, #13805, #13807, #13821, #13822, #14208, #14220, #14322, #14580, #14585) were written to `src/changelog.d/`, which the release compiler never reads, so they shipped without release notes; they are moved to the repo-root `changelog.d/` and land in this release. The release compile now fails loudly while any fragment sits under `src/changelog.d/`, so a stray can no longer disappear silently ([#18264](https://github.com/hivecommons/hive/issues/18264)). diff --git a/src/changelog.d/fixed-adopted-pr-rebase.md b/changelog.d/fixed-adopted-pr-rebase.md similarity index 100% rename from src/changelog.d/fixed-adopted-pr-rebase.md rename to changelog.d/fixed-adopted-pr-rebase.md diff --git a/src/changelog.d/fixed-contributor-claim-starvation.md b/changelog.d/fixed-contributor-claim-starvation.md similarity index 100% rename from src/changelog.d/fixed-contributor-claim-starvation.md rename to changelog.d/fixed-contributor-claim-starvation.md diff --git a/src/changelog.d/fixed-cost-per-agent-copilot-sessions.md b/changelog.d/fixed-cost-per-agent-copilot-sessions.md similarity index 100% rename from src/changelog.d/fixed-cost-per-agent-copilot-sessions.md rename to changelog.d/fixed-cost-per-agent-copilot-sessions.md diff --git a/changelog.d/fixed-supersession-sweep-stage-machine.md b/changelog.d/fixed-supersession-sweep-stage-machine.md new file mode 100644 index 0000000000..2a823f2fc6 --- /dev/null +++ b/changelog.d/fixed-supersession-sweep-stage-machine.md @@ -0,0 +1 @@ +- Supersession sweep: escalation now goes through the stage engine (`needs-human` + `Parked` fact → `stage/085-needs-decision` in the same pass) instead of a bare `needs-human` beside an active lane stage, and a hive-authored PR at L6 whose claimed issue another merged PR closed but which touches files that PR did not is resolved by the hive itself — update-branch onto base, re-measure, rewrite `Closes #N` to `Refs #N (closed by #M; …)` and continue, or self-close when nothing meaningful remains — rather than handed to a person. diff --git a/src/changelog.d/fixed-upgrade-drain-visible-to-hub.md b/changelog.d/fixed-upgrade-drain-visible-to-hub.md similarity index 100% rename from src/changelog.d/fixed-upgrade-drain-visible-to-hub.md rename to changelog.d/fixed-upgrade-drain-visible-to-hub.md diff --git a/src/changelog.d/README.md b/src/changelog.d/README.md index 7e78f4616d..dd881a83ef 100644 --- a/src/changelog.d/README.md +++ b/src/changelog.d/README.md @@ -3,7 +3,9 @@ Changelog fragments go in [`changelog.d/`](../../changelog.d/README.md) at the **repository root**, not here under `src/`. `src/scripts/compile-changelog.sh` only reads the root directory, so a fragment placed here is never compiled into -`CHANGELOG.md`, and the `changelog-fragment-guard` check rejects it (#11919). +`CHANGELOG.md`, the `changelog-fragment-guard` check rejects it (#11919), and +`compile-changelog.sh` refuses to cut a release while one sits here (#18264). +From inside `src/`, the right path is `../changelog.d/`. Name the file `changelog.d/-.md` and make its content a single `- ` bullet. If you already added one here, move it: diff --git a/src/changelog.d/fixed-supersession-sweep-stage-machine.md b/src/changelog.d/fixed-supersession-sweep-stage-machine.md deleted file mode 100644 index d65c1a538a..0000000000 --- a/src/changelog.d/fixed-supersession-sweep-stage-machine.md +++ /dev/null @@ -1 +0,0 @@ -Supersession sweep: escalation now goes through the stage engine (`needs-human` + `Parked` fact → `stage/085-needs-decision` in the same pass) instead of a bare `needs-human` beside an active lane stage, and a hive-authored PR at L6 whose claimed issue another merged PR closed but which touches files that PR did not is resolved by the hive itself — update-branch onto base, re-measure, rewrite `Closes #N` to `Refs #N (closed by #M; …)` and continue, or self-close when nothing meaningful remains — rather than handed to a person. diff --git a/src/docs/knowledge/changelog-fragment-exemptions.md b/src/docs/knowledge/changelog-fragment-exemptions.md index 0ee32a6335..1a1e4f7845 100644 --- a/src/docs/knowledge/changelog-fragment-exemptions.md +++ b/src/docs/knowledge/changelog-fragment-exemptions.md @@ -24,4 +24,4 @@ Exempt automatically — no fragment and no label needed: Other test-adjacent changes (`testdata/` fixtures, non-`_test.go` test helpers) and non-user-visible `src/` code changes (refactors, dependency bumps) need the `no-changelog` label instead of a fragment. -`changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled and the guard rejects it. +`changelog.d/` is at the repository root, not under `src/` — `src/changelog.d/` is never compiled, the guard rejects it, and the release compile fails while any fragment sits there (#18264). From inside `src/`, write `../changelog.d/`. diff --git a/src/scripts/compile-changelog.sh b/src/scripts/compile-changelog.sh index da089b4a46..58097de06b 100755 --- a/src/scripts/compile-changelog.sh +++ b/src/scripts/compile-changelog.sh @@ -43,6 +43,10 @@ # release, so one such fragment silently freezes every later merge. # - Each fragment is deleted after a successful compile, so `git add -A # changelog.d` in the release commit records the consumption. +# - Any fragment (other than README.md) under src/changelog.d/ next to the +# changelog is a LOUD failure before anything else runs: that directory +# is never compiled, so its entries would otherwise be lost (#18264). +# Override the checked path with STRANDED_FRAGDIR. # # Usage: src/scripts/compile-changelog.sh [changelog-path] [fragments-dir] # changelog-path default CHANGELOG.md @@ -76,6 +80,30 @@ if [[ ! -f "$CHANGELOG" ]]; then exit 1 fi +# Release-time backstop for misplaced fragments (#11919, #18264). Only the +# repo-root changelog.d/ is compiled; a fragment under src/changelog.d/ is +# never read, so its entry silently never reaches CHANGELOG.md. The PR guard +# rejects such fragments, but twice PRs merged with it red (161 strays cleaned +# by #11928, 14 more on v5 and 81 on v6 by #18264). Fail loudly here, before +# the no-op exits below, so a stray shows up as a red release job on the very +# next merge instead of disappearing for weeks. The directory is resolved next +# to the changelog so fixture runs in a temp dir never see the real repo. +STRANDED_FRAGDIR="${STRANDED_FRAGDIR:-$(dirname -- "$CHANGELOG")/src/changelog.d}" +if [[ -d "$STRANDED_FRAGDIR" ]]; then + stranded=0 + shopt -s nullglob + for f in "$STRANDED_FRAGDIR"/*.md; do + [[ "$(basename "$f")" == "README.md" ]] && continue + echo "::error file=${f}::fragment is under src/changelog.d/, which is never compiled — run: git mv ${f} ${FRAGDIR}/$(basename "$f")" >&2 + stranded=1 + done + shopt -u nullglob + if [[ "$stranded" -ne 0 ]]; then + echo "::error::refusing to compile while fragments sit in ${STRANDED_FRAGDIR}/ — move them to ${FRAGDIR}/ (see ${FRAGDIR}/README.md)." >&2 + exit 1 + fi +fi + if [[ ! -d "$FRAGDIR" ]]; then echo "No ${FRAGDIR}/ directory — nothing to compile." exit 0 diff --git a/src/scripts/test-compile-changelog.sh b/src/scripts/test-compile-changelog.sh index 80ac652ffb..28205e8e10 100755 --- a/src/scripts/test-compile-changelog.sh +++ b/src/scripts/test-compile-changelog.sh @@ -19,6 +19,8 @@ # would change the derived semver bump); # - the compiled result is exactly what derive-release-version.sh needs: # an added- fragment flips an empty Unreleased to a minor release. +# - a fragment stranded under src/changelog.d/ (never compiled) fails the +# compile loudly, and the repository itself carries none (#18264); # - the release move targets the real `## Unreleased` heading line, not a # prose/backtick mention that appears before it. # @@ -206,6 +208,52 @@ else fi fi +# --------------------------------------------------------------------------- +# Case 5d: a fragment stranded under src/changelog.d/ fails the compile +# (#18264). That directory is never compiled, so 14 v5 and 81 v6 entries sat +# there unreleased; the release job must go red instead of shipping without +# them. This holds even with no root fragments at all (the stray alone must +# not look like a no-op), and README.md there is the pointer, not a fragment. +# --------------------------------------------------------------------------- +dir=$(new_case 5d) +mkdir -p "$dir/src/changelog.d" +printf -- 'pointer to the real directory\n' > "$dir/src/changelog.d/README.md" +cp "$dir/CHANGELOG.md" "$tmp/case5d.before" +if ( cd "$dir" && bash "$compile" CHANGELOG.md changelog.d ) > "$tmp/case5d-readme.out" 2>&1; then + note_ok "a README.md alone under src/changelog.d/ is not a stranded fragment" +else + note_fail "README.md under src/changelog.d/ must not fail the compile: $(cat "$tmp/case5d-readme.out")" +fi +printf -- '- a stranded fix ([#14](https://example.invalid/14)).\n' > "$dir/src/changelog.d/fixed-14-stranded.md" +if ( cd "$dir" && bash "$compile" CHANGELOG.md changelog.d ) > "$tmp/case5d.out" 2>&1; then + note_fail "a fragment under src/changelog.d/ must fail the compile even with no root fragments" +else + if grep -q 'src/changelog.d/fixed-14-stranded.md' "$tmp/case5d.out" \ + && cmp -s "$dir/CHANGELOG.md" "$tmp/case5d.before" \ + && [[ -f "$dir/src/changelog.d/fixed-14-stranded.md" ]]; then + note_ok "a stranded src/changelog.d/ fragment fails loudly, naming the file, with CHANGELOG.md untouched" + else + note_fail "stranded-fragment failure must name the file and leave everything untouched: $(cat "$tmp/case5d.out")" + fi +fi +printf -- '- a real fix ([#15](https://example.invalid/15)).\n' > "$dir/changelog.d/fixed-15-real.md" +if ( cd "$dir" && bash "$compile" CHANGELOG.md changelog.d ) > "$tmp/case5d-mixed.out" 2>&1; then + note_fail "a stranded fragment must fail the compile even beside valid root fragments" +elif [[ -f "$dir/changelog.d/fixed-15-real.md" ]] && cmp -s "$dir/CHANGELOG.md" "$tmp/case5d.before"; then + note_ok "a stranded fragment blocks the compile before any root fragment is consumed" +else + note_fail "a stranded fragment must leave root fragments and CHANGELOG.md untouched" +fi + +# The repository itself must carry no stranded fragments: the live +# src/changelog.d/ holds only its README pointer (#18264). +repo_stranded=$(find "$script_dir/../changelog.d" -maxdepth 1 -type f -name '*.md' ! -name README.md 2>/dev/null | sort) +if [[ -z "$repo_stranded" ]]; then + note_ok "the repository has no fragments under src/changelog.d/" +else + note_fail "fragments under src/changelog.d/ are never compiled; git mv them to the repo-root changelog.d/: $(echo "$repo_stranded" | tr '\n' ' ')" +fi + dir=$(new_case 5c) git init -q "$dir" git -C "$dir" config user.email test@example.com From 8d0cea9c96d7af024f9ce0eaa15adeb946a9291d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:21:46 +0000 Subject: [PATCH 02/72] =?UTF-8?q?=F0=9F=8C=B1=20build(deps):=20Bump=20ws?= =?UTF-8?q?=20from=208.22.1=20to=208.23.0=20in=20/src/proxy=20(#18367)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [ws](https://github.com/websockets/ws) from 8.22.1 to 8.23.0. - [Release notes](https://github.com/websockets/ws/releases) - [Commits](https://github.com/websockets/ws/compare/8.22.1...8.23.0) --- updated-dependencies: - dependency-name: ws dependency-version: 8.23.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- src/proxy/package-lock.json | 8 ++++---- src/proxy/package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/proxy/package-lock.json b/src/proxy/package-lock.json index f28302412e..0ad0e2ca35 100644 --- a/src/proxy/package-lock.json +++ b/src/proxy/package-lock.json @@ -12,7 +12,7 @@ "http-proxy-middleware": "^4.2.1" }, "devDependencies": { - "ws": "^8.22.1" + "ws": "^8.23.0" } }, "node_modules/accepts": { @@ -965,9 +965,9 @@ "license": "ISC" }, "node_modules/ws": { - "version": "8.22.1", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.1.tgz", - "integrity": "sha512-oyL6OPYme/CmiFvNuGzeoxCJ4nOrZE2O1FwM9MWM1AsGri6nLXB2pg+lNA8aLeXMSav0J6eIVS1j6vUPzUtK9g==", + "version": "8.23.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.23.0.tgz", + "integrity": "sha512-wCkmX8QMOrKjgO8HW2WyDbTSGeqkocxgDzS9iR79rEAexty6/2qzilx3Ag8Tqf9ykop3irLKle0MtVn5qjVnoQ==", "dev": true, "license": "MIT", "engines": { diff --git a/src/proxy/package.json b/src/proxy/package.json index 7b0937a24e..96f5ca474f 100644 --- a/src/proxy/package.json +++ b/src/proxy/package.json @@ -14,6 +14,6 @@ "http-proxy-middleware": "^4.2.1" }, "devDependencies": { - "ws": "^8.22.1" + "ws": "^8.23.0" } } From 3ba6656f3d6e6ce68999d0bad877b9903504f457 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 16 Nov 2026 03:22:01 +0000 Subject: [PATCH 03/72] =?UTF-8?q?=F0=9F=8C=B1=20build(deps):=20Bump=20ws?= =?UTF-8?q?=20from=208.22.1=20to=208.23.0=20in=20/dashboard=20(#18371)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [ws](https://github.com/websockets/ws) from 8.22.1 to 8.23.0. - [Release notes](https://github.com/websockets/ws/releases) - [Commits](https://github.com/websockets/ws/compare/8.22.1...8.23.0) --- updated-dependencies: - dependency-name: ws dependency-version: 8.23.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- dashboard/package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dashboard/package-lock.json b/dashboard/package-lock.json index bbfb4b88be..06abdc526d 100644 --- a/dashboard/package-lock.json +++ b/dashboard/package-lock.json @@ -838,9 +838,9 @@ "license": "ISC" }, "node_modules/ws": { - "version": "8.22.1", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.1.tgz", - "integrity": "sha512-oyL6OPYme/CmiFvNuGzeoxCJ4nOrZE2O1FwM9MWM1AsGri6nLXB2pg+lNA8aLeXMSav0J6eIVS1j6vUPzUtK9g==", + "version": "8.23.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.23.0.tgz", + "integrity": "sha512-wCkmX8QMOrKjgO8HW2WyDbTSGeqkocxgDzS9iR79rEAexty6/2qzilx3Ag8Tqf9ykop3irLKle0MtVn5qjVnoQ==", "license": "MIT", "engines": { "node": ">=10.0.0" From bf1bce362125a4b82dc429b18eae384a1eab2570 Mon Sep 17 00:00:00 2001 From: hive-release-bot Date: Mon, 16 Nov 2026 03:28:31 +0000 Subject: [PATCH 04/72] =?UTF-8?q?=F0=9F=94=96=20release:=20v5.276.3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Automated release commit. Compiles changelog.d/ fragments and moves the CHANGELOG.md Unreleased section into a dated v5.276.3 entry. See src/docs/releases.md. Signed-off-by: hive-release-bot --- CHANGELOG.md | 6 ++++++ changelog.d/changed-remove-workflow-survey-binary.md | 1 - 2 files changed, 6 insertions(+), 1 deletion(-) delete mode 100644 changelog.d/changed-remove-workflow-survey-binary.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 86402146b4..e59c30c4ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,12 @@ Hive did not historically maintain a complete changelog. This file starts a prag ## Unreleased +## 2026-11-16 (v5.276.3) + +### Changed + +- Removed an accidentally committed 4.4 MB compiled `workflow-survey` binary from the repository. + ## 2026-11-16 (v5.276.2) ### Fixed diff --git a/changelog.d/changed-remove-workflow-survey-binary.md b/changelog.d/changed-remove-workflow-survey-binary.md deleted file mode 100644 index 92d41c699a..0000000000 --- a/changelog.d/changed-remove-workflow-survey-binary.md +++ /dev/null @@ -1 +0,0 @@ -- Removed an accidentally committed 4.4 MB compiled `workflow-survey` binary from the repository. From 9b6a6f566d84d6472fe5641f0d6653af79f1fa89 Mon Sep 17 00:00:00 2001 From: Andy Anderson Date: Sun, 15 Nov 2026 22:29:46 -0500 Subject: [PATCH 05/72] =?UTF-8?q?=E2=9C=A8=20Inbox:=20transcription=20prog?= =?UTF-8?q?ress=20with=20time=20remaining=20(#18373)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🐛 Inbox: show why Transcribe is unavailable instead of hiding it Pending items with audio now carry transcribe_unavailable (disabled, no_key, no_consent, budget); the UI renders a disabled Transcribe control with the reason and a settings link for owner/read-write, reason text only for read users. Pending text for every source now says hive can transcribe with Deepgram. Signed-off-by: Andy Anderson * 🐛 Inbox: inject transcribe-reason helper in inbox-item tests, keep Plaud pending phrasing Signed-off-by: Andy Anderson * ✨ Inbox: transcription progress with time remaining Queued and running transcriptions show a progress bar with phase, percent, time left and elapsed time; queued items show their place in line. Runs execute one at a time in FIFO order with live in-memory progress exposed on items and on the new lightweight GET /api/inbox/transcriptions. The ETA is measured when a provider reports processed audio, else estimated from the hive's measured speed (EMA of the real-time factor per provider/model, stored with the usage ledger) or a conservative typical speed. inbox.transcription.provider accepts auto (new default), whisper, gemini or deepgram; auto resolves by availability (whisper, gemini, deepgram). The settings panel gains a provider selector with per-provider readiness, and pending, consent and setup text is provider-neutral. Signed-off-by: Andy Anderson --------- Signed-off-by: Andy Anderson --- .../added-inbox-transcription-progress.md | 1 + .../fixed-inbox-transcribe-discoverability.md | 1 + dashboard/openapi.json | 201 +++++++++++++- dashboard/test/inbox-item.test.js | 2 +- src/cmd/hive/boot_inbox.go | 8 +- src/docs/api-reference/knowledge.md | 3 +- src/docs/env-vars.md | 2 +- src/docs/inbox-transcription.md | 128 +++++++-- src/docs/network-requirements.md | 2 +- src/pkg/config/inbox_transcription.go | 54 ++-- src/pkg/config/inbox_transcription_test.go | 9 +- src/pkg/dashboard/api_inbox.go | 21 ++ .../dashboard/api_inbox_transcribe_test.go | 37 +++ src/pkg/dashboard/inbox_transcribe.test.js | 177 ++++++++++++- src/pkg/dashboard/static-src/css/inbox.css | 2 + .../dashboard/static-src/js/config-state.js | 2 +- src/pkg/dashboard/static-src/js/inbox.js | 221 ++++++++++++++-- src/pkg/dashboard/static/index.html | 227 +++++++++++++--- src/pkg/inbox/inbox.go | 4 + src/pkg/inbox/service.go | 8 +- src/pkg/inbox/transcription.go | 99 +++++-- src/pkg/inbox/transcription_progress.go | 246 ++++++++++++++++++ src/pkg/inbox/transcription_progress_test.go | 227 ++++++++++++++++ src/pkg/inbox/transcription_providers.go | 99 +++++++ src/pkg/inbox/transcription_sweep.go | 9 - src/pkg/inbox/transcription_sweep_test.go | 4 +- src/pkg/inbox/transcription_test.go | 44 ++++ src/pkg/inbox/transcripts.go | 81 +++++- src/pkg/transcribe/deepgram.go | 3 + src/pkg/transcribe/fake.go | 11 + src/pkg/transcribe/progress.go | 93 +++++++ src/pkg/transcribe/transcribe.go | 8 +- 32 files changed, 1888 insertions(+), 146 deletions(-) create mode 100644 changelog.d/added-inbox-transcription-progress.md create mode 100644 changelog.d/fixed-inbox-transcribe-discoverability.md create mode 100644 src/pkg/inbox/transcription_progress.go create mode 100644 src/pkg/inbox/transcription_progress_test.go create mode 100644 src/pkg/inbox/transcription_providers.go create mode 100644 src/pkg/transcribe/progress.go diff --git a/changelog.d/added-inbox-transcription-progress.md b/changelog.d/added-inbox-transcription-progress.md new file mode 100644 index 0000000000..97bba0ed8d --- /dev/null +++ b/changelog.d/added-inbox-transcription-progress.md @@ -0,0 +1 @@ +- Inbox: a queued or running transcription now shows a progress bar with the phase, percent, "about N min left" and elapsed time (queued items show how many are ahead), refreshed every 3 seconds from the new lightweight `GET /api/inbox/transcriptions`; the time left is measured where the provider reports progress and otherwise estimated from this hive's own measured speed per provider. `inbox.transcription.provider` now accepts `auto` (the new default), `whisper`, `gemini` or `deepgram`, with a provider selector and per-provider readiness in Inbox ⚙ → Transcription; `auto` picks whisper, then Gemini, then Deepgram by availability, and existing `provider: deepgram` configs are unchanged. Pending and consent text no longer assumes Deepgram. diff --git a/changelog.d/fixed-inbox-transcribe-discoverability.md b/changelog.d/fixed-inbox-transcribe-discoverability.md new file mode 100644 index 0000000000..7cf9ff0be1 --- /dev/null +++ b/changelog.d/fixed-inbox-transcribe-discoverability.md @@ -0,0 +1 @@ +- Inbox: pending recordings now show a disabled 🎧 Transcribe control with the reason (transcription off, missing Deepgram key, consent, or budget) and a link to Inbox ⚙ → Transcription, instead of hiding it; pending text for Plaud, Zoom, Teams, Discord, Meet, Webex, Fireflies, Fathom and Otter now says hive can transcribe with Deepgram. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index ee3b20bb02..1b7aab7a8b 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -38858,8 +38858,8 @@ "tags": [ "Knowledge" ], - "summary": "Transcribe one pending inbox item with Deepgram", - "description": "Owner or read-write. Queues a machine transcription of a pending item (no summary, no transcript) on this hive, with the hive owner's own Deepgram key (`inbox.transcription.api_key_env`, default `DEEPGRAM_API_KEY`). The hive downloads the audio itself and streams it to Deepgram; the presigned link is never forwarded, stored or logged. The transcript stays on this spoke. Checks that need no upload (no audio, too long, daily cap, monthly budget) are recorded as `skipped` and answered 200. Each run is audited as `inbox_transcribe`.", + "summary": "Transcribe one pending inbox item", + "description": "Owner or read-write. Queues a machine transcription of a pending item (no summary, no transcript) on this hive with the resolved `inbox.transcription.provider` (`auto` picks whisper, then gemini, then deepgram by availability; see inbox-transcription.md). The hive downloads the audio itself; the presigned link is never forwarded, stored or logged. With deepgram the audio is streamed to Deepgram under the owner's key (`inbox.transcription.api_key_env`, default `DEEPGRAM_API_KEY`). Runs execute one at a time in queue order; the returned state carries `queue_position` while waiting. The transcript stays on this spoke. Checks that need no upload (no audio, too long, daily cap, monthly budget) are recorded as `skipped` and answered 200. Each run is audited as `inbox_transcribe`.", "parameters": [ { "name": "source", @@ -38922,6 +38922,45 @@ "updated_at": { "type": "string", "format": "date-time" + }, + "phase": { + "type": "string", + "enum": [ + "downloading", + "decoding", + "transcribing", + "finalizing" + ], + "description": "Current phase while running" + }, + "progress": { + "type": "number", + "description": "0 to 1 while running; estimated runs stop at 0.95 until done" + }, + "estimated": { + "type": "boolean", + "description": "Progress and ETA come from the provider's typical or this hive's measured speed, not measured output" + }, + "started_at": { + "type": "string", + "format": "date-time", + "description": "When the run started (running only)" + }, + "audio_seconds": { + "type": "number", + "description": "Recording length in seconds, when known" + }, + "processed_seconds": { + "type": "number", + "description": "Audio transcribed so far, when the provider measures it (whisper)" + }, + "eta_seconds": { + "type": "number", + "description": "Estimated seconds left; absent when unknown" + }, + "queue_position": { + "type": "integer", + "description": "Jobs ahead of this one while queued" } } } @@ -38971,6 +39010,45 @@ "updated_at": { "type": "string", "format": "date-time" + }, + "phase": { + "type": "string", + "enum": [ + "downloading", + "decoding", + "transcribing", + "finalizing" + ], + "description": "Current phase while running" + }, + "progress": { + "type": "number", + "description": "0 to 1 while running; estimated runs stop at 0.95 until done" + }, + "estimated": { + "type": "boolean", + "description": "Progress and ETA come from the provider's typical or this hive's measured speed, not measured output" + }, + "started_at": { + "type": "string", + "format": "date-time", + "description": "When the run started (running only)" + }, + "audio_seconds": { + "type": "number", + "description": "Recording length in seconds, when known" + }, + "processed_seconds": { + "type": "number", + "description": "Audio transcribed so far, when the provider measures it (whisper)" + }, + "eta_seconds": { + "type": "number", + "description": "Estimated seconds left; absent when unknown" + }, + "queue_position": { + "type": "integer", + "description": "Jobs ahead of this one while queued" } } } @@ -39042,6 +39120,125 @@ } } }, + "/api/inbox/transcriptions": { + "get": { + "tags": [ + "Knowledge" + ], + "summary": "Live progress of queued and running Inbox transcriptions", + "description": "Dashboard auth, like `GET /api/inbox`. Lists queued and running machine transcriptions in queue order with phase, progress (0 to 1), elapsed start, ETA and queue position. Reads no source or connector fact, so the Inbox polls it every few seconds while a job runs; an item that leaves the list has finished (re-read `GET /api/inbox` for its outcome). `Cache-Control: no-store`.", + "responses": { + "200": { + "description": "Active transcriptions", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "active": { + "type": "array", + "items": { + "type": "object", + "properties": { + "source": { + "type": "string" + }, + "id": { + "type": "string" + }, + "state": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "queued", + "running" + ] + }, + "reason": { + "type": "string" + }, + "attempts": { + "type": "integer" + }, + "provider": { + "type": "string" + }, + "model": { + "type": "string" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "phase": { + "type": "string", + "enum": [ + "downloading", + "decoding", + "transcribing", + "finalizing" + ], + "description": "Current phase while running" + }, + "progress": { + "type": "number", + "description": "0 to 1 while running; estimated runs stop at 0.95 until done" + }, + "estimated": { + "type": "boolean", + "description": "Progress and ETA come from the provider's typical or this hive's measured speed, not measured output" + }, + "started_at": { + "type": "string", + "format": "date-time", + "description": "When the run started (running only)" + }, + "audio_seconds": { + "type": "number", + "description": "Recording length in seconds, when known" + }, + "processed_seconds": { + "type": "number", + "description": "Audio transcribed so far, when the provider measures it (whisper)" + }, + "eta_seconds": { + "type": "number", + "description": "Estimated seconds left; absent when unknown" + }, + "queue_position": { + "type": "integer", + "description": "Jobs ahead of this one while queued" + } + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "The Inbox is not available", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "error": { + "type": "string" + } + } + } + } + } + } + } + } + }, "/api/inbox/settings": { "get": { "tags": [ diff --git a/dashboard/test/inbox-item.test.js b/dashboard/test/inbox-item.test.js index 0d52dc3fc1..02f6fe4d3e 100644 --- a/dashboard/test/inbox-item.test.js +++ b/dashboard/test/inbox-item.test.js @@ -48,7 +48,7 @@ function makeContext(role) { Array, }; vm.createContext(ctx); - for (const fn of ['inboxSourceIcon', 'inboxItemKey', 'inboxViewerCanPlay', 'inboxApiPath', 'inboxFmtDuration', 'inboxStatePill', 'inboxSummaryHtml', 'inboxTranscriptHtml', 'inboxTranscriptionHtml', 'inboxItemHtml']) { + for (const fn of ['inboxSourceIcon', 'inboxItemKey', 'inboxViewerCanPlay', 'inboxApiPath', 'inboxFmtDuration', 'inboxStatePill', 'inboxSummaryHtml', 'inboxTranscriptHtml', 'inboxTxUnavailableText', 'inboxTxEtaText', 'inboxTxElapsedText', 'inboxTxProgressHtml', 'inboxTranscriptionHtml', 'inboxItemHtml']) { vm.runInContext(extractFunction(fn), ctx); } return ctx; diff --git a/src/cmd/hive/boot_inbox.go b/src/cmd/hive/boot_inbox.go index 4360c5988f..392f9c8a70 100644 --- a/src/cmd/hive/boot_inbox.go +++ b/src/cmd/hive/boot_inbox.go @@ -48,9 +48,11 @@ func (b *boot) bootInbox(baseDir string) { b.inboxSvc = svc b.logger.Info("inbox started", "sources", len(srcs), "rules", len(b.cfg.Inbox.Rules)) if tx := b.cfg.Inbox.Transcription; tx.Enabled { - // Transcription uploads audio from the hive process itself, so a - // locked-down spoke must allow this egress (network-requirements.md). - b.logger.Info("inbox transcription enabled", "mode", tx.EffectiveMode(), "provider", tx.EffectiveProvider(), "egress", strings.Join(inbox.TranscriptionEgressHosts(tx), ",")) + // Transcription reaches the provider from the hive process itself, + // so a locked-down spoke must allow this egress + // (network-requirements.md). auto is logged as what it resolves to. + st := svc.TranscriptionSettings() + b.logger.Info("inbox transcription enabled", "mode", st.Mode, "provider", st.Provider, "resolved_provider", st.ResolvedProvider, "egress", strings.Join(st.EgressHosts, ",")) } } diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index 7d1f28c303..387faded64 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -72,7 +72,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/inbox/settings` | Dashboard auth/session | Auto-routing rules, default RFC repo, dibs URL, destination readiness | `pkg/dashboard/api_inbox.go:26` | | `POST` | `/api/inbox/settings` | Owner only | Update `inbox.rules` / `inbox.spek.repo` / `inbox.dibs.url` in the runtime config (omitted fields unchanged) | `pkg/dashboard/api_inbox.go:27` | | `GET` | `/api/inbox/{source}/{id}/content` | Dashboard auth/session | Full text of one item: `{title, summary, transcript, highlights, markdown, pending, provenance}`, from the fact or live from the source while the fact has no text yet (404 unknown item, 502 source unreachable) | `pkg/dashboard/api_inbox.go:28` | -| `POST` | `/api/inbox/{source}/{id}/transcribe` | Owner or read-write | Queue a machine transcription of one pending item with the owner's own Deepgram key (202 `{source, item_id, state}`; 200 when skipped up front: no audio, too long, budget); audited per run as `inbox_transcribe` (403 role, 404 unknown item, 409 queued/running/already transcribed/has text, 412 disabled or not consented); see [inbox-transcription.md](../inbox-transcription.md) | `pkg/dashboard/api_inbox.go:31` | +| `POST` | `/api/inbox/{source}/{id}/transcribe` | Owner or read-write | Queue a machine transcription of one pending item with the resolved `inbox.transcription.provider` (auto: whisper, then gemini, then deepgram); runs execute one at a time in queue order (202 `{source, item_id, state}`; 200 when skipped up front: no audio, too long, budget); audited per run as `inbox_transcribe` (403 role, 404 unknown item, 409 queued/running/already transcribed/has text, 412 disabled or not consented); see [inbox-transcription.md](../inbox-transcription.md) | `pkg/dashboard/api_inbox.go:31` | +| `GET` | `/api/inbox/transcriptions` | Dashboard auth | Live progress of queued and running transcriptions in queue order (`{active: [{source, id, state}]}` with `phase`, `progress`, `estimated`, `started_at`, `audio_seconds`, `processed_seconds`, `eta_seconds`, `queue_position`); reads no source, so the Inbox polls it every 3 s while a job runs; `Cache-Control: no-store`; see [inbox-transcription.md](../inbox-transcription.md) | `pkg/dashboard/api_inbox.go:32` | | `GET` | `/api/inbox/{source}/{id}/audio` | Owner or read-write | Mint a fresh short-lived audio/video link for one item (`{url, expires_at}`; Plaud: presigned, 24h; Zoom: audio-only or video `download_url` with a one-hour download token; Webex: the recording's temporary direct audio (else MP4) download link, valid 3 hours; Teams and Google Meet: 404, no browser-playable link; Slack huddles: 404, Slack keeps no huddle audio; Otter: the conversation's MP3 download link (`GET /conversations/{id}/audio`), minted per click; Granola: 404, Granola keeps no meeting audio; Limitless: 404, Pendant audio is served only behind the API key; Fathom: the signed url of a recording download (`POST /recordings/{id}/download`, audio-only recordings complete at once, video is polled), valid about 24 hours; Fireflies: the transcript's hashed `audio_url` (else `video_url`), valid 24 hours, Pro plan or higher); never stored by the hive, replied with `Cache-Control: no-store`, audited as `inbox_audio` (403 role, 404 unknown item or no audio, 502 source unreachable) | `pkg/dashboard/api_inbox.go:29` | | `GET` | `/api/meetings/settings` | Owner only | Meetings settings: `enabled`, `enabled_env_override`, `running`, `vexa_url`, `vexa_key_set`, `discord_token_set`, `transcribe_token_set` (secrets are never returned) and `effective` values of the other `meetings.*` keys ([env vars](../env-vars.md#meetings-quorum)) | `pkg/dashboard/api_meetings.go:123` | | `POST` | `/api/meetings/settings` | Owner only | Update `meetings.enabled` and `meetings.vexa.url`, and write the Vexa tenant key, Discord bot token and transcription service token to keystore-sealed secret files (`""` clears one): `{enabled?, vexa_url?, vexa_api_key?, discord_token?, transcribe_token?}`. Returns the settings with `restart_required`; 400 on an invalid value. Audited as `meetings_settings` | `pkg/dashboard/api_meetings.go:124` | diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md index dfd998ee4c..47321bd7c4 100644 --- a/src/docs/env-vars.md +++ b/src/docs/env-vars.md @@ -130,7 +130,7 @@ behavior. [Maintenance limitations](#keeping-this-reference-current) still apply | `HIVE_DOSSIER_CACHE_MAX_ENTRIES` | No | `512` | Caps each public dossier cache. Bounds username-spray memory while keeping normal contributor reuse hot. | | `HIVE_CONTRIBUTOR_KNOWLEDGE_EXPORT_MAX_FACTS` | No | `80` | Caps the number of facts returned by the contributor knowledge export API. Unset, non-numeric, or non-positive values fall back to the default. | | `HIVE_PUBLIC_REPOS` | No | none | Comma-separated, case-insensitive allowlist of additional Gource project names the dashboard's public war-room view may render, beyond the always-allowed default (`hive`). | -| `DEEPGRAM_API_KEY` | No | none | The hive owner's own Deepgram API key for Inbox transcription (`inbox.transcription`, [inbox-transcription.md](inbox-transcription.md)). Read at run time; `inbox.transcription.api_key_env` names a different variable. Never stored in `hive.yaml`, never shown (the UI reports only key present / missing). | +| `DEEPGRAM_API_KEY` | No | none | The hive owner's own Deepgram API key for Inbox transcription with `inbox.transcription.provider: deepgram`, or `auto` when whisper and Gemini are unavailable ([inbox-transcription.md](inbox-transcription.md)). Read at run time; `inbox.transcription.api_key_env` names a different variable. Never stored in `hive.yaml`, never shown (the UI reports only key present / missing). | | `HIVE_INBOX_TRANSCRIPTION_MAX_DURATION_MINUTES` | No | `120` | Overrides `inbox.transcription.max_duration_minutes`: longer recordings are skipped before upload. Non-numeric or non-positive values fall back to the config / default. | | `HIVE_INBOX_TRANSCRIPTION_MAX_BYTES` | No | `524288000` | Overrides `inbox.transcription.max_bytes`: an audio download larger than this is cut and the item skipped as too large. | | `HIVE_INBOX_TRANSCRIPTION_MONTHLY_BUDGET_MINUTES` | No | `600` | Overrides `inbox.transcription.monthly_budget_minutes`: audio minutes this hive may send per UTC month. | diff --git a/src/docs/inbox-transcription.md b/src/docs/inbox-transcription.md index f8baa607e3..caa70f0e27 100644 --- a/src/docs/inbox-transcription.md +++ b/src/docs/inbox-transcription.md @@ -1,30 +1,65 @@ -# Inbox transcription (Deepgram) +# Inbox transcription Some recordings reach the [Inbox](inbox-voice-sources.md) without any text: a Plaud recording that was never transcribed in the Plaud app, or a meeting recording without captions. Inbox transcription turns the audio of such an -item into a speaker-labelled transcript with [Deepgram](https://deepgram.com) -so it can be read, routed to an RFC or dibs, and searched like any other item. +item into a timestamped transcript so it can be read, routed to an RFC or +dibs, and searched like any other item. It is **off by default**. +## Providers + +`inbox.transcription.provider` is one of: + +| Provider | Account | Where the audio goes | Speakers | Speed | +| --- | --- | --- | --- | --- | +| `whisper` | none (built into the hive image) | nowhere: decoded and transcribed on the hive | no | a few minutes for a 5-minute recording on 2 to 4 vCPU | +| `gemini` | the hive's own Gemini credentials | Google (Gemini API) | yes | under a minute for a 5-minute recording | +| `deepgram` | the owner's Deepgram key | Deepgram (`mip_opt_out=true`) | yes | seconds, plus the upload | +| `auto` (default) | | whichever provider it picks | | | + +`auto` resolves on every run, by what is available on this hive: + +| Order | `auto` uses | when | +| --- | --- | --- | +| 1 | `whisper` | the whisper engine is in the hive image (its model is on disk or may be downloaded) | +| 2 | `gemini` | whisper is unavailable and the hive has Gemini credentials | +| 3 | `deepgram` | whisper and Gemini are unavailable and the Deepgram key is set | +| 4 | `deepgram`, not ready | nothing is available: items show "provider not ready" and nothing is sent | + +An explicit `whisper`, `gemini` or `deepgram` is used as is, with no +fallback: Deepgram is used only when the owner selects it (or as the last +resort of `auto`). Existing configs with `provider: deepgram` keep their +behaviour; the ⚙ settings panel has always written `provider: deepgram` +explicitly. A config that never set `provider` now resolves through +`auto`. The ⚙ panel shows each provider's readiness (whisper engine and +model present, Gemini credentials present, Deepgram key present) without +ever showing a key, and which provider `auto` currently picks +(`settings.transcription.resolved_provider`, `providers[]`). + +Hive versions without the whisper or Gemini engine report them as *not +ready* (`not_installed`), so `auto` behaves as `deepgram` there. + ## Each hive owns its transcriptions Transcription is spoke-local. Nothing about it is shared or central: -- **Your key, your account.** The hive owner supplies their own Deepgram API - key through an environment variable on their hive. Audio is billed to that +- **Your hive, your account.** whisper runs on the hive's own CPU with no + account. Gemini and Deepgram run under the hive's own credentials (the + owner's Deepgram key, the hive's Gemini credentials) and bill that account. No hive pays for, or sees, another hive's transcriptions. - **Your data volume.** The transcript is written only to this hive's data volume, under `connector-state/transcripts//.json` (mode `0600`, written atomically). It is not sent to the hub, to other spokes, or back to the recording's source. - **Your budget.** Monthly minutes, a daily item cap and size/duration limits - are configured per hive and checked before any audio is uploaded. + are configured per hive and checked before any audio is uploaded. With + whisper the minutes budget limits CPU time on the hive, not money. ## Security and privacy model -- **Audio leaves the hive to Deepgram.** When an item is transcribed, the +- **Deepgram: audio leaves the hive to Deepgram.** When an item is transcribed with Deepgram, the hive downloads the recording from its source (for Plaud, a fresh presigned link minted for this run, as the ▶ Play button does) and streams the bytes to `https://api.deepgram.com/v1/listen` under the owner's key. Deepgram @@ -42,8 +77,9 @@ Transcription is spoke-local. Nothing about it is shared or central: never its value. - **Consent.** Recordings contain other people's voices. Enabling transcription requires `consent_acknowledged: true`; the ⚙ settings panel - shows a notice that the audio is sent to Deepgram under the hive owner's - own account before the checkbox can be ticked. A config with + shows a notice for the selected provider before the checkbox can be + ticked: with whisper the audio stays on the hive, with Gemini or Deepgram + it is sent to Google or Deepgram under the hive's own account. A config with `enabled: true` and no consent is rejected at load and on save. - **Untrusted text.** A machine transcript is third-party speech like any other Inbox text. It reaches spektacular and agent prompts through the same @@ -60,7 +96,7 @@ inbox: transcription: enabled: false # off by default mode: manual # manual | auto - provider: deepgram # the only provider today + provider: auto # auto | whisper | gemini | deepgram model: nova-3 # Deepgram pre-recorded model api_key_env: DEEPGRAM_API_KEY # env var holding the owner's key sources: [] # auto mode only transcribes these source names @@ -99,18 +135,56 @@ calls `POST /api/inbox/{source}/{id}/transcribe`: cap or the monthly minutes budget (`budget`). These are recorded as **skipped** with the reason and answered `200`. 3. Otherwise the item is **queued** (`202`) and runs in the background, one - job at a time per hive: **running** → **done**, **failed** (with the - reason), or **skipped** (`too large`, when the download is bigger than - `max_bytes`; a limit reader also cuts a stream without a length). + job at a time per hive in the order they were queued: **running** → + **done**, **failed** (with the reason), or **skipped** (`too large`, when + the download is bigger than `max_bytes`; a limit reader also cuts a + stream without a length). 4. HTTP 429, 5xx and network errors are retried up to 3 attempts with exponential backoff; each attempt downloads the audio afresh. A failed or skipped item keeps its **Retry transcription** button. The item shows a pill for the state (with a spinner while queued or running, -and the failure reason). Once done, the item is no longer pending and its +and the failure reason with a **Retry transcription** button for owners and +read-write sessions). Once done, the item is no longer pending and its *Transcript* disclosure shows the text under **Transcript (machine: deepgram/nova-3)**, in the same `[mm:ss] Speaker N: text` line shape as Plaud -and meeting transcripts. +and meeting transcripts (`[mm:ss] text` when the provider has no speakers). + +## Progress and time remaining + +While an item is queued or running it shows a progress bar (the connector +sync styling) with the phase, the percentage, *about N min left* and the +elapsed time; a queued item shows how many transcriptions are ahead of it. +The item state carries: + +| Field | | +| --- | --- | +| `phase` | `downloading`, `decoding` (whisper), `transcribing`, `finalizing` | +| `progress` | 0 to 1 | +| `estimated` | true when progress and ETA come from a speed estimate rather than measured output | +| `started_at` | when the run started | +| `audio_seconds` / `processed_seconds` | recording length / audio transcribed so far (measured providers) | +| `eta_seconds` | estimated seconds left | +| `queue_position` | jobs ahead while queued | + +How progress is computed: + +- **Measured (whisper).** Processed audio seconds over the recording + length. The ETA is the transcribing time so far divided by progress, times + what is left, smoothed so one fast or slow tick does not make the text + jump. Below 2% it uses the estimate instead. +- **Estimated (Deepgram, Gemini, and whisper before its first tick).** One + request has no streaming progress, so progress is elapsed time over the + expected time, held at 95% until done. The expected time is this hive's + measured speed for that provider and model, an exponential moving + average of the real-time factor of its finished runs (stored with the + usage ledger, `_usage.json` `speeds`), or until the first run a + conservative typical speed: Deepgram 10 s + 0.05x, Gemini 15 s + 0.15x, + whisper 5 s + 0.6x the recording length. + +The Inbox polls `GET /api/inbox/transcriptions` every 3 seconds while a job +is queued or running and redraws only that item's progress; it stops when +nothing is busy and re-reads the Inbox once when a job finishes. ## Automatic transcription (auto mode) @@ -137,11 +211,13 @@ today's runs against the daily limit, and the egress the hive needs. ## Egress -The hive process itself uploads the audio, so a spoke behind an egress -allowlist must allow `api.deepgram.com:443` while transcription is enabled -(and the source's audio host, which playback already needs). Nothing is -needed while transcription is off. `settings.transcription.egress_hosts` and -the boot log line `inbox transcription enabled` name the host. See +Egress depends on the provider (always plus the source's audio host, which +playback already needs; nothing while transcription is off): + +- `deepgram`: the hive process uploads the audio to `api.deepgram.com:443`. + +`settings.transcription.egress_hosts` (for the provider `auto` resolves to) +and the boot log line `inbox transcription enabled` name the hosts. See [network-requirements.md](network-requirements.md). ## Upstream text wins @@ -154,24 +230,26 @@ still serves the item's content. ## Cost -Deepgram bills the owner's account per audio minute. The audit entry carries +whisper costs CPU time on the hive only. Deepgram bills the owner's account per audio minute. The audit entry carries an estimate from Deepgram's published pay-as-you-go nova-3 price; the Deepgram invoice is authoritative. The monthly budget counts the audio length Deepgram reports for each finished run. -## Providers +## Adapters `src/pkg/transcribe` defines a small `Transcriber` interface (`Name`, `Transcribe(ctx, Audio) (Result, error)`) with a Deepgram adapter and a fake -for tests. Another provider (for example an OpenAI-compatible -`/audio/transcriptions` endpoint) can be added behind the same interface. +for tests. Adapters report phases and measured progress through +`Audio.Progress`; `transcribe.TypicalSpeed` holds each provider's default +speed for the estimate. ## API | Method | Path | Access | | | --- | --- | --- | --- | | `POST` | `/api/inbox/{source}/{id}/transcribe` | Owner or read-write | Queue a transcription (202), or report an up-front skip (200); 409 busy/done/has text, 412 disabled or not consented, 404 unknown item | -| `GET` | `/api/inbox` | Dashboard auth | Items carry `transcription` (`status`, `reason`, `attempts`, `provider`, `model`, `updated_at`) and `transcribable`; `settings.transcription` carries the effective config, `key_present`, `month_minutes_used` and `today_items` | +| `GET` | `/api/inbox` | Dashboard auth | Items carry `transcription` (`status`, `reason`, `attempts`, `provider`, `model`, `updated_at`, and the progress fields above while busy) and `transcribable`; `settings.transcription` carries the effective config, `resolved_provider`, `resolved_model`, `providers[]` (`name`, `available`, `status`, `detail`, `audio_goes_to`, `model`), `key_present`, `month_minutes_used` and `today_items` | +| `GET` | `/api/inbox/transcriptions` | Dashboard auth | Queued and running transcriptions in queue order with live progress (`active[]`: `source`, `id`, `state`); reads no source, for polling | | `GET` | `/api/inbox/{source}/{id}/content` | Dashboard auth | Falls back to the machine transcript, with `transcript_label` | See also [api-reference/knowledge.md](api-reference/knowledge.md). diff --git a/src/docs/network-requirements.md b/src/docs/network-requirements.md index 9135566408..cf72decdf2 100644 --- a/src/docs/network-requirements.md +++ b/src/docs/network-requirements.md @@ -43,7 +43,7 @@ Reverse proxies, Routes, and Ingresses must preserve HTTP upgrade headers and lo | Kubernetes API | In-cluster spokes/hub | Used for health/provisioning/route discovery when those features are configured. | | Login provider issuers | Hub with multi-provider login | GitHub OAuth endpoints, plus the OIDC issuer/JWKS hosts for each configured provider (e.g. `accounts.google.com`, `login.microsoftonline.com`, `sso.redhat.com`, or your IBMid/custom issuer). | | OCI Object Storage (`objectstorage..oraclecloud.com`) | Hub running DR backups | Only when the opt-in backup CronJob is deployed; see [backup-restore.md](backup-restore.md). | -| `api.deepgram.com:443` | Spokes with Inbox transcription | Only when `inbox.transcription.enabled` is true. The hive process itself (not an agent) uploads recording audio to Deepgram under the owner's own key, so it does not go through the agent MITM proxy; the hive also downloads the audio from the source's audio host (for Plaud, its presigned CDN link). See [inbox-transcription.md](inbox-transcription.md). | +| `api.deepgram.com:443` | Spokes with Inbox transcription via Deepgram | Only when `inbox.transcription.enabled` is true and the provider is (or `auto` resolves to) `deepgram`. The hive process itself (not an agent) uploads recording audio to Deepgram under the owner's own key, so it does not go through the agent MITM proxy; the hive also downloads the audio from the source's audio host (for Plaud, its presigned CDN link). See [inbox-transcription.md](inbox-transcription.md). | ## Egress through a corporate forward proxy diff --git a/src/pkg/config/inbox_transcription.go b/src/pkg/config/inbox_transcription.go index aa2617a1de..f956feca22 100644 --- a/src/pkg/config/inbox_transcription.go +++ b/src/pkg/config/inbox_transcription.go @@ -4,6 +4,7 @@ import ( "fmt" "os" "regexp" + "slices" "strconv" "strings" "time" @@ -19,11 +20,28 @@ const ( InboxTranscriptionModeAuto = "auto" ) -// Inbox transcription defaults. Each spoke transcribes with its owner's own -// provider key; these bound what one hive spends on its own account. +// Inbox transcription providers (inbox.transcription.provider). const ( - // DefaultInboxTranscriptionProvider is the only provider built today. - DefaultInboxTranscriptionProvider = "deepgram" + // InboxTranscriptionProviderAuto picks the first available provider in + // the order whisper, gemini, deepgram (see inbox-transcription.md). + InboxTranscriptionProviderAuto = "auto" + // InboxTranscriptionProviderWhisper is whisper.cpp built into the hive + // image: no account, the audio never leaves the spoke. + InboxTranscriptionProviderWhisper = "whisper" + // InboxTranscriptionProviderGemini uses the hive's own Gemini credentials. + InboxTranscriptionProviderGemini = "gemini" + // InboxTranscriptionProviderDeepgram uses the owner's Deepgram key. + InboxTranscriptionProviderDeepgram = "deepgram" +) + +// InboxTranscriptionProviders lists the accepted provider values. +var InboxTranscriptionProviders = []string{InboxTranscriptionProviderAuto, InboxTranscriptionProviderWhisper, InboxTranscriptionProviderGemini, InboxTranscriptionProviderDeepgram} + +// Inbox transcription defaults. Each spoke transcribes on its own hive or +// with its owner's own provider account; these bound what one hive spends. +const ( + // DefaultInboxTranscriptionProvider picks a provider by availability. + DefaultInboxTranscriptionProvider = InboxTranscriptionProviderAuto // DefaultInboxTranscriptionModel is Deepgram's pre-recorded model. DefaultInboxTranscriptionModel = "nova-3" // DefaultInboxTranscriptionKeyEnv names the variable holding the key. @@ -51,17 +69,18 @@ const ( ) // InboxTranscription is `inbox.transcription`: spoke-local machine -// transcription for Inbox recordings that arrive without text. The audio is -// sent to the provider under the hive owner's own account and key; the -// transcript is stored only on this spoke. Off by default, and enabling it -// requires consent_acknowledged: true. +// transcription for Inbox recordings that arrive without text. Depending on +// the provider the audio stays on the spoke (whisper) or is sent to the +// provider under the hive's own account (gemini, deepgram); the transcript +// is stored only on this spoke. Off by default, and enabling it requires +// consent_acknowledged: true. type InboxTranscription struct { Enabled bool `yaml:"enabled,omitempty" json:"enabled"` // Mode is manual (default) or auto. Mode string `yaml:"mode,omitempty" json:"mode,omitempty"` - // Provider is deepgram (default). + // Provider is auto (default), whisper, gemini or deepgram. Provider string `yaml:"provider,omitempty" json:"provider,omitempty"` - // Model defaults to nova-3. + // Model is the Deepgram model; it defaults to nova-3. Model string `yaml:"model,omitempty" json:"model,omitempty"` // APIKeyEnv names the environment variable holding the provider key // (default DEEPGRAM_API_KEY). The key itself never lives in hive.yaml. @@ -81,7 +100,8 @@ type InboxTranscription struct { // DailyMaxItems caps transcription runs per UTC day. DailyMaxItems int `yaml:"daily_max_items,omitempty" json:"daily_max_items,omitempty"` // ConsentAcknowledged records that the owner read the notice: recordings - // contain other people's voices and the audio is sent to the provider. + // contain other people's voices, and where the chosen provider sends the + // audio (nowhere for whisper; Google or Deepgram otherwise). ConsentAcknowledged bool `yaml:"consent_acknowledged,omitempty" json:"consent_acknowledged"` } @@ -98,7 +118,9 @@ func (t InboxTranscription) EffectiveMode() string { return InboxTranscriptionModeManual } -// EffectiveProvider returns the provider, defaulting to deepgram. +// EffectiveProvider returns the configured provider, defaulting to auto. +// Which provider auto resolves to depends on what is available on the hive +// (inbox.Service resolves it). func (t InboxTranscription) EffectiveProvider() string { if p := strings.TrimSpace(t.Provider); p != "" { return p @@ -106,7 +128,7 @@ func (t InboxTranscription) EffectiveProvider() string { return DefaultInboxTranscriptionProvider } -// EffectiveModel returns the model, defaulting to nova-3. +// EffectiveModel returns the Deepgram model, defaulting to nova-3. func (t InboxTranscription) EffectiveModel() string { if m := strings.TrimSpace(t.Model); m != "" { return m @@ -192,8 +214,8 @@ func ValidateInboxTranscription(t InboxTranscription) error { default: return fmt.Errorf("inbox.transcription.mode %q: must be %s or %s", t.Mode, InboxTranscriptionModeManual, InboxTranscriptionModeAuto) } - if p := t.EffectiveProvider(); p != DefaultInboxTranscriptionProvider { - return fmt.Errorf("inbox.transcription.provider %q: only %s is supported", p, DefaultInboxTranscriptionProvider) + if p := t.EffectiveProvider(); !slices.Contains(InboxTranscriptionProviders, p) { + return fmt.Errorf("inbox.transcription.provider %q: must be one of %s", p, strings.Join(InboxTranscriptionProviders, ", ")) } if !inboxEnvNameRe.MatchString(t.EffectiveAPIKeyEnv()) { return fmt.Errorf("inbox.transcription.api_key_env %q: must be an environment variable name", t.APIKeyEnv) @@ -210,7 +232,7 @@ func ValidateInboxTranscription(t InboxTranscription) error { } } if t.Enabled && !t.ConsentAcknowledged { - return fmt.Errorf("inbox.transcription.enabled requires inbox.transcription.consent_acknowledged: true (recordings contain other people's voices and the audio is sent to the provider under the hive owner's account)") + return fmt.Errorf("inbox.transcription.enabled requires inbox.transcription.consent_acknowledged: true (recordings contain other people's voices; with gemini or deepgram the audio is sent to that provider under the hive's own account)") } return nil } diff --git a/src/pkg/config/inbox_transcription_test.go b/src/pkg/config/inbox_transcription_test.go index af97213bfc..2f21b0a44d 100644 --- a/src/pkg/config/inbox_transcription_test.go +++ b/src/pkg/config/inbox_transcription_test.go @@ -10,7 +10,7 @@ import ( func TestInboxTranscriptionDefaults(t *testing.T) { var tr InboxTranscription - if tr.Enabled || tr.Active() || tr.EffectiveMode() != "manual" || tr.EffectiveProvider() != "deepgram" || tr.EffectiveModel() != "nova-3" { + if tr.Enabled || tr.Active() || tr.EffectiveMode() != "manual" || tr.EffectiveProvider() != "auto" || tr.EffectiveModel() != "nova-3" { t.Fatalf("defaults = %+v", tr) } if tr.EffectiveAPIKeyEnv() != "DEEPGRAM_API_KEY" || !tr.EffectiveDiarize() || tr.EffectiveLanguage() != "auto" { @@ -63,7 +63,7 @@ func TestInboxTranscriptionConfiguredAndEnvOverrides(t *testing.T) { func TestValidateInboxTranscriptionRejects(t *testing.T) { cases := map[string]InboxTranscription{ "mode": {Mode: "sometimes"}, - "provider": {Provider: "whisper"}, + "provider": {Provider: "openai"}, "key env": {APIKeyEnv: "not a name"}, "language": {Language: "english please"}, "negative": {MaxBytes: -1}, @@ -75,6 +75,11 @@ func TestValidateInboxTranscriptionRejects(t *testing.T) { t.Errorf("%s: want error", name) } } + for _, p := range InboxTranscriptionProviders { + if err := ValidateInboxTranscription(InboxTranscription{Provider: p}); err != nil { + t.Errorf("provider %s: %v", p, err) + } + } err := ValidateInbox(InboxConfig{Transcription: InboxTranscription{Enabled: true}}) if err == nil || !strings.Contains(err.Error(), "consent_acknowledged") { t.Fatalf("ValidateInbox must apply the consent gate: %v", err) diff --git a/src/pkg/dashboard/api_inbox.go b/src/pkg/dashboard/api_inbox.go index 240a60f759..0325c4f23e 100644 --- a/src/pkg/dashboard/api_inbox.go +++ b/src/pkg/dashboard/api_inbox.go @@ -29,6 +29,7 @@ func (s *Server) registerInboxRoutes() { s.mux.HandleFunc("GET /api/inbox/{source}/{id}/audio", s.handleInboxAudio) s.mux.HandleFunc("POST /api/knowledge/connectors/{name}/auth/complete", s.handleKnowledgeConnectorAuthComplete) s.mux.HandleFunc("POST /api/inbox/{source}/{id}/transcribe", s.handleInboxTranscribe) + s.mux.HandleFunc("GET /api/inbox/transcriptions", s.handleInboxTranscriptions) } // inboxSourceReadTimeout bounds one read that may spawn the source's MCP @@ -191,6 +192,26 @@ func (s *Server) handleInboxTranscribe(w http.ResponseWriter, r *http.Request) { jsonStatusResponse(w, code, InboxTranscribeResponse{Source: it.Source, ItemID: it.ID, State: st}) } +// InboxTranscriptionsResponse is GET /api/inbox/transcriptions. +type InboxTranscriptionsResponse struct { + // Active lists queued and running transcriptions in queue order, with + // phase, progress, ETA and queue position. + Active []inbox.ActiveTranscription `json:"active"` +} + +// handleInboxTranscriptions (dashboard auth, like the listing) returns the +// live state of queued and running transcriptions only. It reads no source +// and no connector fact, so the Inbox can poll it every few seconds while a +// job runs; an item that leaves the list has finished. +func (s *Server) handleInboxTranscriptions(w http.ResponseWriter, _ *http.Request) { + svc, ok := s.inboxService(w) + if !ok { + return + } + w.Header().Set("Cache-Control", "no-store") + jsonResponse(w, InboxTranscriptionsResponse{Active: svc.ActiveTranscriptions()}) +} + // InboxSourceStatus is one configured source as the Inbox header shows it. type InboxSourceStatus struct { Type string `json:"type"` diff --git a/src/pkg/dashboard/api_inbox_transcribe_test.go b/src/pkg/dashboard/api_inbox_transcribe_test.go index 742df23b81..c3a141de1f 100644 --- a/src/pkg/dashboard/api_inbox_transcribe_test.go +++ b/src/pkg/dashboard/api_inbox_transcribe_test.go @@ -212,3 +212,40 @@ func TestInboxSettingsTranscriptionConsentGate(t *testing.T) { t.Fatal("settings must never carry a key value") } } + +// TestInboxTranscriptionsLiveProgress: GET /api/inbox/transcriptions lists +// queued and running jobs with their place in line, never caches, and is +// empty once the queue drains. +func TestInboxTranscriptionsLiveProgress(t *testing.T) { + s, svc, _, _ := newTranscribeTestServer(t, config.InboxTranscription{Enabled: true, ConsentAcknowledged: true}) + var pending []func() + svc.Run = func(fn func()) { pending = append(pending, fn) } + for _, id := range []string{"rec-1", "rec-2"} { + if rec := doPostRole(s, "/api/inbox/plaud/"+id+"/transcribe", "owner", true, nil); rec.Code != http.StatusAccepted { + t.Fatalf("queue %s = %d: %s", id, rec.Code, rec.Body.String()) + } + } + rec := doGet(s, "/api/inbox/transcriptions") + if rec.Code != http.StatusOK || rec.Header().Get("Cache-Control") != "no-store" { + t.Fatalf("live = %d %q", rec.Code, rec.Header().Get("Cache-Control")) + } + var got InboxTranscriptionsResponse + if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil || len(got.Active) != 2 || got.Active[1].ID != "rec-2" || got.Active[1].State.QueuePosition != 1 { + t.Fatalf("live body = %s %v", rec.Body.String(), err) + } + if strings.Contains(rec.Body.String(), "dg-test-key") || strings.Contains(rec.Body.String(), "topsecret") { + t.Fatalf("live body leaks: %s", rec.Body.String()) + } + for _, fn := range pending { + fn() + } + rec = doGet(s, "/api/inbox/transcriptions") + if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil || got.Active == nil || len(got.Active) != 0 { + t.Fatalf("drained = %s %v", rec.Body.String(), err) + } + + empty, _ := apiServer(t) + if rec := doGet(empty, "/api/inbox/transcriptions"); rec.Code != http.StatusNotFound { + t.Fatalf("no inbox = %d", rec.Code) + } +} diff --git a/src/pkg/dashboard/inbox_transcribe.test.js b/src/pkg/dashboard/inbox_transcribe.test.js index 3af2074df8..ce1fe37af9 100644 --- a/src/pkg/dashboard/inbox_transcribe.test.js +++ b/src/pkg/dashboard/inbox_transcribe.test.js @@ -40,7 +40,7 @@ const itemHarness = ({ role = 'owner', status = 202, body = { state: { status: ' }; const h = new Function('ctx', 'fetch', 'escapeHtml', 'formatDashboardDateTime', 'showToast', 'renderInbox', 'fetchInbox', 'INBOX_TX_STATUS_LABELS', 'const window = ctx.window; const _inboxTranscribing = ctx._inboxTranscribing; const _inboxContent = ctx._inboxContent;\n' + - fnSrc('inboxViewerCanPlay') + '\n' + fnSrc('inboxApiPath') + '\n' + fnSrc('inboxTranscriptionHtml') + '\n' + fnSrc('inboxTranscribe') + '\n' + + fnSrc('inboxViewerCanPlay') + '\n' + fnSrc('inboxApiPath') + '\n' + fnSrc('inboxTxUnavailableText') + '\n' + fnSrc('inboxTxEtaText') + '\n' + fnSrc('inboxTxElapsedText') + '\n' + fnSrc('inboxTxProgressHtml') + '\n' + fnSrc('inboxTranscriptionHtml') + '\n' + fnSrc('inboxTranscribe') + '\n' + 'return { inboxTranscriptionHtml, inboxTranscribe };'); const api = h(ctx, fetch, escapeHtml, s => 'at ' + s, (msg, kind) => calls.toasts.push([msg, kind]), () => { calls.renders++; }, async () => { calls.refreshes++; }, LABELS); @@ -116,12 +116,13 @@ const formRoot = fields => ({ }); const settingsHarness = () => new Function('escapeHtml', 'yamlHint', 'INBOX_TX_BYTES_PER_MB', - fnSrc('inboxTranscriptionFormHtml') + '\n' + fnSrc('inboxTranscriptionUsageHtml') + '\n' + fnSrc('inboxReadTranscription') + '\nreturn { inboxTranscriptionFormHtml, inboxTranscriptionUsageHtml, inboxReadTranscription };', + fnSrc('inboxTxProviderInfo') + '\n' + fnSrc('inboxTxConsentText') + '\n' + fnSrc('inboxTxProviderHtml') + '\n' + + fnSrc('inboxTranscriptionFormHtml') + '\n' + fnSrc('inboxTranscriptionUsageHtml') + '\n' + fnSrc('inboxReadTranscription') + '\nreturn { inboxTranscriptionFormHtml, inboxTranscriptionUsageHtml, inboxReadTranscription, inboxTxConsentText, inboxTxProviderHtml };', )(escapeHtml, p => '' + p + '', BYTES_PER_MB); test('settings section shows the consent notice, key status and every yaml key', () => { const { inboxTranscriptionFormHtml } = settingsHarness(); - let out = inboxTranscriptionFormHtml({ enabled: false, api_key_env: 'MY_DG', key_present: false, max_bytes: 524288000, sources: ['plaud'] }); + let out = inboxTranscriptionFormHtml({ enabled: false, provider: 'deepgram', api_key_env: 'MY_DG', key_present: false, max_bytes: 524288000, sources: ['plaud'] }); assert.match(out, /other people's voices/); assert.match(out, /Deepgram under the hive owner's Deepgram account and key/); assert.match(out, /data-inbox-tx-field="consent_acknowledged">/); @@ -142,7 +143,7 @@ test('reading the section enforces consent and converts the size limit', () => { const { inboxReadTranscription } = settingsHarness(); const base = { enabled: { checked: true }, consent_acknowledged: { checked: false }, mode: { value: 'auto' }, model: { value: 'nova-3' }, - api_key_env: { value: ' MY_DG ' }, sources: { value: 'plaud, zoom,' }, diarize: { checked: true }, language: { value: 'auto' }, + provider: { value: 'deepgram' }, api_key_env: { value: ' MY_DG ' }, sources: { value: 'plaud, zoom,' }, diarize: { checked: true }, language: { value: 'auto' }, monthly_budget_minutes: { value: '300' }, daily_max_items: { value: '-2' }, max_duration_minutes: { value: '90' }, max_mb: { value: '10' }, }; const refused = inboxReadTranscription(formRoot(base), {}); @@ -156,6 +157,11 @@ test('reading the section enforces consent and converts the size limit', () => { const off = inboxReadTranscription(formRoot({ enabled: { checked: false } }), null); assert.strictEqual(off.transcription.enabled, false, 'disabling needs no consent'); assert.strictEqual(off.transcription.mode, 'manual'); + assert.strictEqual(off.transcription.provider, 'auto', 'no selector and no current value means auto'); + const kept = inboxReadTranscription(formRoot({ enabled: { checked: false } }), { provider: 'deepgram' }); + assert.strictEqual(kept.transcription.provider, 'deepgram', 'an existing explicit provider is kept'); + const picked = inboxReadTranscription(formRoot({ enabled: { checked: false }, provider: { value: 'whisper' } }), { provider: 'deepgram' }); + assert.strictEqual(picked.transcription.provider, 'whisper', 'the selector wins'); assert.strictEqual(inboxReadTranscription(null), null); assert.strictEqual(inboxReadTranscription({ querySelector: () => null }), null, 'no section, no transcription payload'); }); @@ -175,3 +181,166 @@ test('settings section shows month usage, egress and the auto-mode source hint', assert.match(inboxTranscriptionUsageHtml(undefined), /0 of 0 minutes used/); assert.match(inboxTranscriptionFormHtml({ month_minutes_used: 1, monthly_budget_minutes: 600 }), /data-inbox-tx-usage="1"/); }); + +const TX_REASONS = [ + ['disabled', /Transcription is off: enable it in Inbox ⚙ → Transcription/], + ['no_key', /The transcription provider is not ready on this hive: see Inbox ⚙ → Transcription/], + ['no_consent', /Consent not acknowledged/], + ['budget', /Monthly budget used/], +]; + +test('unavailable transcription shows a disabled button, the reason and a setup link for owner and read-write', () => { + for (const [code, re] of TX_REASONS) { + for (const role of ['owner', 'read-write']) { + const { api } = itemHarness({ role }); + const out = api.inboxTranscriptionHtml({ source: 'plaud', id: 'r1', pending: true, transcribe_unavailable: code }, 'plaud/r1'); + assert.match(out, /]*inbox-transcribe[^>]*disabled/, code + ' ' + role); + assert.doesNotMatch(out, /data-action="inboxTranscribe"/, 'disabled control must not fire the action'); + assert.match(out, re, code); + assert.match(out, /data-action="inboxOpenSettings"/, 'setup link for ' + role); + } + } +}); + +test('read-only viewers see only the reason text, no control or link', () => { + for (const [code, re] of TX_REASONS) { + for (const role of ['read-only', '']) { + const { api } = itemHarness({ role }); + const out = api.inboxTranscriptionHtml({ source: 'plaud', id: 'r1', pending: true, transcribe_unavailable: code }, 'plaud/r1'); + assert.match(out, re, code); + assert.doesNotMatch(out, /'; + html += ' ' + escapeHtml(why) + ''; + if (canAct) html += ' '; + } else if (it.transcribable && inboxViewerCanPlay()) { const inflight = _inboxTranscribing.has(key); const retry = st && (st.status === 'failed' || st.status === 'skipped'); html += ''; } - return html ? '
' + html + '
' : ''; + return html ? '
' + html + '
' : ''; + } + + // inboxTxApplyActive merges the live states from + // GET /api/inbox/transcriptions into the cached items and reports the + // keys that were busy before and are no longer listed (finished). + function inboxTxApplyActive(items, active) { + const live = {}; + for (const a of active || []) live[a.source + '/' + a.id] = a.state; + const finished = []; + for (const it of items || []) { + const key = it.source + '/' + it.id; + if (live[key]) it.transcription = Object.assign({}, it.transcription || {}, live[key]); + else if (inboxTxBusy(it.transcription)) finished.push(key); + } + return finished; + } + function inboxTxPollSchedule() { + if (_inboxTxPollTimer) return; + _inboxTxPollTimer = setTimeout(inboxTxPoll, INBOX_TX_POLL_MS); + } + // One progress poll: redraw each busy item's slot in place (the rest of + // the Inbox, including a playing recording, is left alone); re-read the + // Inbox once a job finishes; stop when nothing is busy. + async function inboxTxPoll() { + _inboxTxPollTimer = null; + const items = (_inboxCache || {}).items || []; + if (!inboxTxAnyBusy(items)) return; + let finished = []; + try { + const r = await fetch('/api/inbox/transcriptions'); + if (!r.ok) throw new Error('HTTP ' + r.status); + const data = await r.json(); + finished = inboxTxApplyActive(items, data.active); + } catch (e) { + inboxTxPollSchedule(); + return; + } + if (finished.length) { for (const k of finished) delete _inboxContent[k]; await fetchInbox(); return; } + const panel = document.getElementById('inbox-panel'); + for (const it of items) { + if (!inboxTxBusy(it.transcription)) continue; + const key = it.source + '/' + it.id; + const slot = panel ? Array.from(panel.querySelectorAll('[data-inbox-tx-slot]')).find(el => el.getAttribute('data-inbox-tx-slot') === key) : null; + if (slot) slot.outerHTML = inboxTranscriptionHtml(it, key); + } + inboxTxPollSchedule(); } async function inboxTranscribe(src, id) { @@ -448,9 +570,52 @@ '' + buttons + ''; } - // Transcription section: spoke-local Deepgram transcription with the - // owner's own key. The key value is never shown, only whether the named - // variable is set on this hive. + // Provider choices for ⚙ → Transcription: one line on speed, speakers + // and where the audio goes. + function inboxTxProviderInfo() { + return { + auto: 'Picks whisper, then Gemini, then Deepgram: the first one that is ready on this hive.', + whisper: 'Built in, no account: a 5-minute recording takes a few minutes on the hive\'s CPU; no speaker labels; the audio never leaves this hive.', + gemini: 'Uses this hive\'s own Gemini credentials: fast, labels speakers, approximate timestamps; the audio is sent to Google.', + deepgram: 'Uses the owner\'s Deepgram key: fastest, labels speakers; the audio is sent to Deepgram (training opt-out set).' + }; + } + // Where the audio goes for the selected provider, for the consent notice. + // For auto it names what auto resolves to right now. + function inboxTxConsentText(provider, resolved) { + const p = provider === 'auto' ? (resolved || '') : provider; + const dest = { + whisper: 'With whisper the audio stays on this hive: a sandboxed process here decodes and transcribes it and nothing is sent anywhere.', + gemini: 'With Gemini this hive sends the audio to Google (the Gemini API) under the hive\'s own Gemini credentials.', + deepgram: 'With Deepgram this hive sends the audio to Deepgram under the hive owner\'s Deepgram account and key, with Deepgram\'s model-training opt-out set.' + }[p] || 'Depending on the provider the audio stays on this hive (whisper) or is sent to Google (Gemini) or Deepgram under the hive\'s own account.'; + return (provider === 'auto' && resolved ? 'Auto currently picks ' + resolved + '. ' : '') + dest; + } + // Provider selector with each provider's readiness (never a key value). + function inboxTxProviderHtml(tx) { + const info = inboxTxProviderInfo(); + const current = info[tx.provider] ? tx.provider : 'auto'; + const status = {}; + for (const p of (Array.isArray(tx.providers) ? tx.providers : [])) status[p.name] = p; + let opts = ''; + for (const name of ['auto', 'whisper', 'gemini', 'deepgram']) { + const st = status[name]; + const suffix = name === 'auto' ? (tx.resolved_provider ? ' (now: ' + tx.resolved_provider + ')' : '') : (st && !st.available ? ' (not ready)' : ''); + opts += ''; + } + let rows = ''; + for (const name of ['auto', 'whisper', 'gemini', 'deepgram']) { + const st = status[name]; + const pill = name === 'auto' ? '' : (st ? '' + (st.available ? 'ready' : 'not ready') + ' ' + escapeHtml(st.detail || '') : ''); + rows += '
  • ' + name + ': ' + escapeHtml(info[name]) + (pill ? ' ' + pill : '') + '
  • '; + } + return '' + + '
      ' + rows + '
    '; + } + + // Transcription section: spoke-local transcription with whisper (on the + // hive), the hive's Gemini credentials, or the owner's Deepgram key. Key + // values are never shown, only whether they are present on this hive. function inboxTranscriptionFormHtml(tx) { tx = tx || {}; const field = (name, label, value, placeholder, type) => '