Skip to content

✨ ask: hive panel and rollout verification for optional Ask AI help - #19206

Open
clubanderson wants to merge 14 commits into
v5from
feat/ask-hive-panel
Open

clubanderson wants to merge 14 commits into
v5from
feat/ask-hive-panel

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Phase 5 of the Ask AI help design (src/docs/design/dashboard-ask-ai-help.md): the hive panel, self-hosted direct-mode docs and the live verification checklist. It builds on #19200 (hub backend), #19202 (hub panel and the shared component) and #19204 (hive backend and relay), so until those merge this diff also shows them; merge them first, in that order. The phase 5 changes are the commit "ask: hive panel and rollout verification for optional Ask AI help".

Fixes #19184

What it does

  • The hive dashboard reuses the hub's panel component (pkg/askai/web/ask-panel.js and .css), served from 'self' at /ask-panel.js and /ask-panel.css only while Ask is on (404 otherwise).
  • The page loads it only when /api/config reports ask_enabled: true (the effective state, including the hosted-only rule for hub mode). With Ask off the page adds nothing and requests nothing for it; there is one empty opener slot in the top bar.
  • Section label: the section nearest the top of the viewport, taken from the dashboard's own section registry (DASHBOARD_SECTION_HELP), or settings / settings-features while the Settings dialog is open. The docs-link fallback follows the same section through dashboardDocsHref, like every "?" mark.
  • No CSP change: a same-origin script and stylesheet added at runtime, allowed by the existing script-src-elem 'self' and style-src-elem 'self'.
  • Docs (src/docs/ask-ai-help.md): turning it on for a self-hosted hive in direct mode (Secret or read-only mount under /secrets, hive.yaml keys), using the panel, and a Verifying a rollout checklist.

Tests

  • Panel assets are 404 with Ask off and served with the right types when on; /api/config reports ask_enabled from the effective settings.
  • The page loader is gated on cfg.ask_enabled === true, loads only same-origin assets, names no third-party host and writes no markup; the dashboard holds exactly one slot and calls the loader from the config bootstrap.
  • The closed section vocabulary covers every hive dashboard section with a help mark, with the same headings (parity test against sections.js).
  • Node test of the panel's view model: only https sources survive and name their host, an answer without one becomes "No cited answer", every other outcome is a notice with the backend's message.

Live verification (prepared, not run)

Nothing was enabled on the hub or any hive. Once the Kapa API key exists, the operator runs the checklist in src/docs/ask-ai-help.md#verifying-a-rollout: hub off then on, a cited answer, a refused fake token, withdrawal, one hosted hive in hub mode (audit lines on hub and hive, no question text), one self-hosted hive in direct mode, the empty-key fallback, switching off again, and checking in Kapa analytics that only the question and the section label arrived.

Adds the ask config block and HIVE_ASK_* env (off by default, inert when
unconfigured, key only from a file under the allowed secret dirs), the
pkg/askai service (Kapa Chat API client pinned to the published
QueryResponse schema, per-person consent store, credential-shape refusal,
source allowlist, plain-text answers, per-person/per-hive/hub-wide limits,
circuit breaker, content-free audit lines) and the hub routes
GET /api/ask/status, PUT/DELETE /api/ask/consent, POST /api/ask and
GET /api/ask/stats. Routes are registered only when the feature is on.

Fixes #19180

Signed-off-by: Andy Anderson <andy@clubanderson.com>
…sleep

The Kapa Chat request is a model request (machine, reasonModelPrompt) in
the new outbound-sites inventory from v5. The in-flight test now waits on
a channel instead of polling with time.Sleep, keeping the sleep ratchet.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Lifts pkg/askai over the 90% package floor: bad vendor JSON, an invalid
thread id dropped, cancellation, the half-open breaker's single trial,
handle eviction, idle-counter pruning, corrupt consent records and the
service defaults.

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Adds the shared panel component (pkg/askai/web: same-origin script and
stylesheet, text-only rendering, consent notice, sources and AI label,
docs-link fallback in every state, keyboard and screen-reader support,
docked layout) and wires it into the hub dashboard only when Ask is on.
With Ask off the dashboard document, its ETag and its headers are
unchanged and the assets are not served. Scale controls show the
effective switch with a help mark.

Fixes #19181

Signed-off-by: Andy Anderson <andy@clubanderson.com>
(cherry picked from commit 2fe253f)
Adds the ask block to hive.yaml (vendor ids never serialised to JSON and
redacted in the config export), the hive dashboard routes
GET /api/ask/status, PUT/DELETE /api/ask/consent and POST /api/ask (404
while off), per-person consent on the hive keyed by dashboard identity,
direct mode with the hive's own key, and hub mode through a new
POST /api/hub/ask/relay on the hub. The relay authenticates the hive with
its per-hive heartbeat bearer, serves hosted hives only in this round,
honours a per-hive disable list and an hourly per-hive quota, and binds
conversation handles to the hive. Settings, Features gains the Ask switch,
mode and section-label toggle.

Fixes #19183

Signed-off-by: Andy Anderson <andy@clubanderson.com>
The hive dashboard loads the shared Ask panel component from 'self' only
when /api/config reports ask_enabled; the section in view or the open
Settings tab labels the question from the closed vocabulary, and the
docs link follows it. /ask-panel.js and /ask-panel.css on the hive answer
404 while Ask is off. Adds a vocabulary parity test against the
dashboard's section registry, a node test of the panel view model, the
self-hosted direct-mode guide and a rollout verification checklist.

Fixes #19184

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
…luded

Signed-off-by: Andy Anderson <andy@clubanderson.com>
Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign nicholasjackson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

This PR conflicts with v5 itself. Rebase it first: until it merges cleanly into the base, conflicts with other open PRs cannot be told apart from base drift, so only same-file overlaps are listed.

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19265 🐛 Name how a sign-off ask was answered on the tracker Review track same files src/docs/api-reference/dashboard-misc.md
src/pkg/dashboard/static/index.html
#19283 🐛 Line up every dashboard sidebar group with the Dashboard indent same files src/pkg/dashboard/static/index.html
#19277 🌱 Skip heavy CI jobs on refresh-only pull request heads same files src/docs/documentation-map.md
#19281 ✨ gauge: show Claude usage credits (on/off, spent of monthly cap) same files src/docs/api-reference/cost-tokens-telemetry.md
src/pkg/dashboard/static/index.html
#19204 ✨ ask: hive backend and hub relay for optional Ask AI help same files changelog.d/added-19180-ask-hub-backend.md
changelog.d/added-19183-ask-hive-backend.md
dashboard/openapi.json
src/docs/api-reference/agents-and-controls.md
src/docs/api-reference/auth.md
src/docs/api-reference/beads.md
src/docs/api-reference/configuration.md
src/docs/api-reference/cost-tokens-telemetry.md
src/docs/api-reference/dashboard-misc.md
src/docs/api-reference/health-status-events.md
src/docs/api-reference/hub-saas.md
src/docs/api-reference/hub-server.md
src/docs/api-reference/inception.md
src/docs/api-reference/knowledge.md
src/docs/api-reference/nous.md
src/docs/api-reference/packs-and-acmm.md
src/docs/api-reference/snapshots-and-style.md
src/docs/ask-ai-help.md
src/docs/documentation-map.md
src/docs/env-vars.md
src/docs/hub-deployment.md
src/docs/settings.md
src/docs/telemetry.md
src/internal/testutil/dashboard_import_allowlist.txt
src/pkg/askai/breaker.go
src/pkg/askai/consent.go
src/pkg/askai/edges_test.go
src/pkg/askai/kapa.go
src/pkg/askai/kapa_test.go
src/pkg/askai/limits.go
src/pkg/askai/relay.go
src/pkg/askai/relay_test.go
src/pkg/askai/sections.go
src/pkg/askai/service.go
src/pkg/askai/service_test.go
src/pkg/askai/sources.go
src/pkg/askai/store_test.go
src/pkg/askai/threads.go
src/pkg/config/ask.go
src/pkg/config/ask_test.go
src/pkg/config/config.go
src/pkg/config/testdata/agent_runtime_golden.json
src/pkg/dashboard/api.go
src/pkg/dashboard/api_ask.go
src/pkg/dashboard/api_ask_test.go
src/pkg/dashboard/api_config_export.go
src/pkg/dashboard/api_governor_features.go
src/pkg/dashboard/import_count_test.go
src/pkg/dashboard/openapi_schema_parity_test.go
src/pkg/dashboard/server.go
src/pkg/dashboard/static-src/js/config-features.js
src/pkg/dashboard/static/index.html
src/pkg/hub/ask.go
src/pkg/hub/ask_relay.go
src/pkg/hub/ask_relay_test.go
src/pkg/hub/ask_test.go
src/pkg/hub/saas.go
src/pkg/hub/saas_users_admin.go
src/pkg/hub/server.go
src/pkg/prosefilter/outbound_sites_test.go
#19202 ✨ ask: hub panel for optional Ask AI help same files changelog.d/added-19180-ask-hub-backend.md
changelog.d/added-19181-ask-hub-panel.md
src/docs/api-reference/hub-saas.md
src/docs/api-reference/hub-server.md
src/docs/env-vars.md
src/docs/hub-deployment.md
src/docs/telemetry.md
src/pkg/askai/breaker.go
src/pkg/askai/consent.go
src/pkg/askai/edges_test.go
src/pkg/askai/kapa.go
src/pkg/askai/kapa_test.go
src/pkg/askai/limits.go
src/pkg/askai/sections.go
src/pkg/askai/service.go
src/pkg/askai/service_test.go
src/pkg/askai/sources.go
src/pkg/askai/store_test.go
src/pkg/askai/threads.go
src/pkg/askai/web.go
src/pkg/askai/web/ask-panel.css
src/pkg/askai/web/ask-panel.js
src/pkg/askai/web_test.go
src/pkg/config/ask.go
src/pkg/config/ask_test.go
src/pkg/hub/ask.go
src/pkg/hub/ask_panel_test.go
src/pkg/hub/ask_test.go
src/pkg/hub/assets/dashboard.html
src/pkg/hub/saas.go
src/pkg/hub/saas_pages.go
src/pkg/hub/saas_users_admin.go
src/pkg/hub/scale_settings.go
src/pkg/hub/server.go
src/pkg/prosefilter/outbound_sites_test.go
#19252 ✨ feature: let spokes sync their own registration repos same files src/docs/api-reference/hub-server.md
#19240 ✨ hub: registration key rotation with a grace window same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
src/docs/hub-deployment.md
#19253 ✨ customers: hub import disclosure, docs and consent views same files src/docs/api-reference/hub-saas.md
src/docs/env-vars.md
src/docs/hub-deployment.md
src/docs/telemetry.md
src/pkg/hub/assets/dashboard.html
#19273 🐛 dashboard: band donuts include Outside so they add up to the BP totals same files src/pkg/dashboard/static/index.html

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UI render evidence

Render evidence captured.

Built from b0828af2bd8b.
Screenshots: download the artifact (sign-in to GitHub required).
Run: https://github.com/hivecommons/hive/actions/runs/44444931419

Page Section Viewport Theme File Size
hive overview desktop light hive-overview-desktop-light.png 326 KB
hive overview desktop dark hive-overview-desktop-dark.png 307 KB
hive overview phone light hive-overview-phone-light.png 467 KB
hive overview phone dark hive-overview-phone-dark.png 464 KB
hub-fleet overview desktop light hub-fleet-overview-desktop-light.png 113 KB
hub-fleet overview desktop dark hub-fleet-overview-desktop-dark.png 115 KB
hub-fleet overview phone light hub-fleet-overview-phone-light.png 265 KB
hub-fleet overview phone dark hub-fleet-overview-phone-dark.png 270 KB
hub-dashboard overview desktop light hub-dashboard-overview-desktop-light.png 338 KB
hub-dashboard overview desktop dark hub-dashboard-overview-desktop-dark.png 344 KB
hub-dashboard overview phone light hub-dashboard-overview-phone-light.png 624 KB
hub-dashboard overview phone dark hub-dashboard-overview-phone-dark.png 656 KB

These are fixture renders, not live data: the page was built from the PR head and filled with synthetic data from src/scripts/fixtures/render-evidence/. They show layout and theming, not how real hives behave. How to read them: src/docs/ui-render-evidence.md.

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

ℹ️ Sentinel: informational, author is trusted (owner), merge is not blocked. Head b0828af2bd8b matched:

  • remote_code_execution: adds a remote-fetch-and-execute, decoded payload, reverse shell or embedded credential (src/pkg/askai/service_test.go)

No sentinel-alert label was added. The finding is recorded in the dashboard Security tab and /api/sentinel; set sentinel.trusted_authors_block: true to block trusted authors too.

@clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Failing checks:

  • test (rest 2/4)

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Scope of this review: I read the phase 5 dashboard front end (src/pkg/dashboard/static-src/js/ask.js, config-features.js, sse-bootstrap.js, topbar.html). I did not read the ~6.5k-line stacked backend and hub code in depth, so nothing below speaks for it.

  • Stacked and conflicting. The head carries the commits of ✨ ask: hub backend for optional Ask AI help #19200, ✨ ask: hub panel for optional Ask AI help #19202 and ✨ ask: hive backend and hub relay for optional Ask AI help #19204 plus merge commits (14 commits, 80 files), and the PR is dirty. The body already says to merge those first; the PR needs a rebase onto v5 once they land, and until then the diff cannot be reviewed as phase 5 alone.
  • Front end looks consistent with the body. loadAskPanel (ask.js) returns early unless cfg.ask_enabled === true, so with Ask off nothing is requested; the call site in sse-bootstrap.js is guarded by typeof loadAskPanel === 'function'. The section id sent comes only from DASHBOARD_SECTION_HELP keys or the two fixed settings ids, matching the "closed vocabulary" claim.
  • Why a human: the feature sends user-typed questions to a third party, which is an external side effect with a privacy notice. The design doc covers it, but the merge order and the final data-flow sign-off are a maintainer call.

@github-actions github-actions Bot removed the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 19, 2026
… does not count them

Signed-off-by: Andy Anderson <andy@clubanderson.com>
… in the dashboard ratchet

Signed-off-by: Andy Anderson <andy@clubanderson.com>
@kubestellar-prow kubestellar-prow Bot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delta re-review (b0828af..8cd49e4). Allowlist entry, config golden ask block and the 68→69 import ratchet are consistent with the new pkg/askai import. The parity-test change is not.

Finding (in-scope, blocks): the delta deletes the GET /ask-panel.js and GET /ask-panel.css entries from routeParityExceptions (src/pkg/dashboard/openapi_route_parity_test.go), but both routes are still registered at src/pkg/dashboard/api.go:87-88. Neither route is in dashboard/openapi.json at this head: grep ask-panel finds nothing, and only /api/ask/status, /api/ask/consent and /api/ask are documented. TestOpenAPISpecCoversEveryRegisteredRoute will therefore report "registered but undocumented: GET /ask-panel.js" and the same for .css. The panel assets are a required part of #19184 item 1, so this red test blocks it.

Fix: either restore the two exceptions removed in the delta, or add /ask-panel.js and /ask-panel.css to dashboard/openapi.json. I recommend restoring the exceptions, because they are static assets and not JSON operations:

 var routeParityExceptions = []routeParityException{
+	{
+		method: "GET", path: "/ask-panel.js",
+		reason: "Ask AI help panel script (#19184): a static same-origin asset " +
+			"served only while ask is on, not a JSON data operation.",
+	},
+	{
+		method: "GET", path: "/ask-panel.css",
+		reason: "Ask AI help panel stylesheet (#19184): a static same-origin " +
+			"asset served only while ask is on, not a JSON data operation.",
+	},
 	{
 		method: "GET", path: "/api/health",

I read the test logic and registrations but did not run the test.

Findings not on a changed line

  • src/pkg/dashboard/openapi_route_parity_test.go:47: Removing the /ask-panel.js and /ask-panel.css exceptions breaks the parity test: api.go:87-88 still registers both routes and openapi.json does not document them. Restore the exceptions (see summary for the diff) or add spec entries.

-- hive: agent=adjudicator-3 backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Merge state is dirty (conflicts with v5). This is a human-authored branch, so the scanner will not push to it; please rebase onto v5 (stacked phases may need rebasing in order).


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

hive/awaiting-rebase: mergeable_state is dirty (stacked on #19200). Not pushing to a human-authored branch; rebase onto v5 once #19200 lands.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

scanner: this PR is CONFLICTING with v5 (stacked Ask AI phases). Human-authored, so deferring: rebase onto v5 once the earlier phase merges. Not pushing to this branch.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

hive/scanner: this PR has merge conflicts with v5 (mergeable_state=dirty). It is human-authored, so the hive will not push to it. Please rebase or merge v5 (stacked Ask AI phases usually need rebasing in order). Deferred until the conflict is resolved.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Scanner: this PR is in a conflicting (dirty) state against its base. Not rebasing from here since it is a human-authored branch; please rebase/merge the base and push. Note that #19202, #19204 and #19206 look like a stack, so rebase in order.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ ask: hive panel and live verification for optional Ask AI help (phase 5 of #19177)

1 participant