Skip to content

✨ ask: hive backend and hub relay for optional Ask AI help - #19204

Open
clubanderson wants to merge 8 commits into
v5from
feat/ask-hive-backend
Open

clubanderson wants to merge 8 commits into
v5from
feat/ask-hive-backend

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Phase 4 of the Ask AI help design (src/docs/design/dashboard-ask-ai-help.md): the hive backend and the hub relay. Builds on #19200 (phase 1: pkg/askai, the ask config type and the hub service), so until #19200 merges this diff also shows phase 1; merge #19200 first. The phase 4 changes are the commit "ask: hive backend and hub relay for optional Ask AI help". Independent of the hub panel (#19202).

Fixes #19183

What it does

  • ask: is now a hive.yaml block (ask.enabled, ask.mode, ask.kapa.*, ask.send_section_label, ask.limits.*), env wins as for the other feature switches. ask.kapa.project_id and ask.kapa.integration_id are json:"-", so no API that encodes the config returns them, and the config export redacts every ask.kapa value. The hub-only relay settings stay env (HIVE_ASK_RELAY_*); the hub has no hive.yaml.
  • Hive dashboard routes GET /api/ask/status, PUT/DELETE /api/ask/consent, POST /api/ask. Every one answers 404 while Ask is off or not fully configured. The person is the authenticated dashboard identity (session, or the hub-verified identity on a hosted spoke), never a body field. Consent is one 0600 file per person under /data/ask-consents/, keyed by the identity (hashed when it is not a safe file name).
  • Modes: direct (a self-hosted hive with its own key file, same service as the hub) and hub (a hosted hive). In hub mode the hive validates the question, refuses credential-shaped input, checks consent and its own per-person limits, then posts only {question, section, conversation} to POST /api/hub/ask/relay with its per-hive heartbeat bearer and X-Hive-ID. It never holds or sends a vendor key, re-filters the hub's answer (sources allowlist, plain text, its own docs link and AI label) and keeps the hub's conversation handle behind a local one bound to the person. A relay refusal (404/401/403) becomes the docs-link fallback; it never falls back to a key.
  • Hub relay: registered only when Ask is on at the hub; authenticates the bearer for the hive id; serves hosted (hub-provisioned, non-byo-) hives only in this round (HIVE_ASK_RELAY_HIVES, default hosted; none turns it off; registered is accepted and treated as hosted, with a TODO(#19177) and a one-time warning: self-hosted registered hives later); HIVE_ASK_RELAY_DISABLED_HIVES refuses single hives; per-hive hourly quota (60, HIVE_ASK_LIMIT_HIVE_PER_HOUR) inside the hub-wide limits; conversation handles are bound to the hive, so hive B cannot continue hive A's thread.
  • Settings, Features: Ask AI help switch (owner), Ask mode and Send the section label, each with a help mark that names what is sent; the dialog says why Ask stays off (for example a self-hosted hive set to hub).
  • Outbound inventory: the relay call is classed as hive-to-hub control traffic.

Tests (behaviour)

  • Off is inert on the hive: unset, switched off and half-configured all answer 404 on every route, create no consent dir and send nothing; CSP and other security headers are byte-identical with Ask on.
  • Direct mode: consent gates, the vendor sees exactly {integration_id, query} with the closed-list label, seeded login and hive id never appear, credential-shaped questions refused, person from the request only, withdrawal blocks; key and vendor ids never in logs.
  • Hub mode: relay call carries the bearer and hive id, no person and no X-API-KEY; self-hosted or hub-less hives stay off with a reason.
  • Relay (hub side): no bearer or another hive's bearer is 401; disabled, not provisioned and byo- hives get relay_disabled (or 401) with zero vendor calls; hive B cannot reuse hive A's handle; the per-hive quota charges hive A only; none and registered modes.
  • RelayAsker: exact body, re-filtering of hostile sources, links, label and docs URL, unknown outcomes and hub errors as fallbacks, local per-person limits; Service.Relay skips person caps but not the hive cap.
  • Settings: features GET/PUT for the three keys, unknown mode rejected, no vendor id in the GET; export redaction of ask.kapa.

Docs: new operator guide src/docs/ask-ai-help.md (linked from the documentation map and Settings), relay section in hub-deployment.md, API reference rows (hive and hub), OpenAPI for the four hive operations, telemetry row updated. static/index.html regenerated from static-src/ (manifest concatenation).

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 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>
@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 kellyaa 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 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. labels Nov 19, 2026
@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 31347e68b369 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.

@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
#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
#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
#19206 ✨ ask: hive panel and rollout verification 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
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/config/ask.go
src/pkg/config/ask_test.go
src/pkg/hub/ask.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
#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
#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>
@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 19, 2026
@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

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

UI render evidence

Render evidence captured.

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

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.

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

@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.

Read pkg/askai/consent.go, pkg/dashboard/api_ask.go and the shared ask-panel.js at this head. The consent path is bounded to one safe path segment, the person comes from the authenticated request and never the body, every route 404s while Ask is off, and the panel renders only with textContent plus https allowlisted links. Looks sound to me; one low-severity note is on the line below. I did not read the relay (relay.go, hub/ask_relay.go) or the hub-side limits in depth.

-- hive: agent=reviewer backend=claude model=claude-sonnet-5-5 claude=2.1.327

Comment thread src/pkg/askai/consent.go
if identity == "" {
return ""
}
if consentStemPattern.MatchString(identity) {

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.

Low: PersonKey returns the identity itself when it already matches the safe-stem pattern, and otherwise h- plus 40 hex of a hash. A username that is literally h-<40 hex> shares a stem with the hashed form of some other identity (an email), so the two would read and write the same consent file. It needs a username shaped like that, so the risk is small, but a one-line fix is to hash every identity, or to reject safe-stem identities that start with h-.

@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
… 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 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 backend and hub relay for optional Ask AI help (phase 4 of #19177)

1 participant