Skip to content

✨ ask: hub backend for optional Ask AI help (phase 1) - #19199

Closed
Danathar wants to merge 2 commits into
v5from
feat/ask-ai-backend-19180
Closed

Danathar wants to merge 2 commits into
v5from
feat/ask-ai-backend-19180

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

What

Phase 1 of the Ask AI help design (src/docs/design/dashboard-ask-ai-help.md): the hub backend only, no panel. Off by default and inert.

  • Config (pkg/config/ask.go): ask: block and HIVE_ASK_* env overrides (env wins). Enabled but a value missing, an unusable mode or a key file outside the allowed secret directory means it stays off with one warning that names a reason and no value. project_id, integration_id and the key path are json:"-" and redacted from the config export.
  • Vendor client (pkg/ask/client.go): POST /query/v1/projects/{project_id}/chat/ (and /query/v1/threads/{thread_id}/chat/ for follow-ups), key in X-API-KEY, non-streaming. The body is exactly integration_id and query. The 200 shape (answer, thread_id, question_answer_id, is_uncertain, relevant_sources[{source_url,title,contains_internal_data}]) was confirmed against the vendor API reference and is pinned by a contract test. Redirects are not followed with the key, and errors carry no URL, id or key.
  • Service (pkg/ask): credential-shaped input refused with FindSecret; length caps; source allowlist (docs site host, and the GitHub docs path under hivecommons/hive), with no allowlisted source giving a "no cited answer" result; closed-vocabulary section label; vendor thread ids kept server-side behind opaque handles bound to the person with a TTL; limits (per person burst and hourly, per hive, hub-wide per minute, in flight, daily budget); circuit breaker; 429 and timeout fall back to a fixed message; audit lines with outcome and counts only; counters by outcome.
  • Hub (pkg/hub/ask.go): per-person consent record (own file keyed like the user record, atomic, 0600, text_version, grant and withdraw, removed with the user), GET/PUT/DELETE /api/ask/consent, POST /api/ask behind a browser session (no bearer fallback, no impersonation), and GET /api/saas/admin/ask/stats. With the switch off every route answers 404 and nothing is written or sent. No CSP is touched.
  • Docs: env-vars.md, hive.yaml.example, the design record's verification note, and a changelog fragment.

Tests

Fake vendor server asserts the exact request body and that seeded secrets, repo names, hive names and logins never appear on the wire, in a response or in a log; off means 404 and no vendor call; consent gates every request (missing, withdrawn, old text version, another person); limits, breaker and thread binding hold; credentials never appear in any response, log or export.

I did not run the test suite locally (AGENTS.md: CI is the verdict); only gofmt -l on the changed files.

Closes #19180

🤖 Generated with Claude Code

-- hive: backend=claude model=claude-sonnet-5-5


🐝 Hive Agent: contributor | SHA: 8050f6d54

Adds the hub backend for the optional Ask AI help, off by default and inert:

- `ask:` config block and HIVE_ASK_* env overrides; if enabled but a value
  is missing or the key file is unusable it stays off and logs one warning
  without values. The key file must sit under the allowed secret directory.
  Project and integration ids are redacted from the config export and never
  appear in JSON.
- pkg/ask: vendor Chat API client (non-streamed, key in X-API-KEY, only
  integration_id and query sent, response shape pinned by a contract test),
  source allowlist, limits (person, hive, hub-wide per minute, in flight,
  daily), circuit breaker, server-side thread handles bound to the person
  with a TTL, and audit lines with outcome and counts only.
- Hub: per-person consent record (own file, atomic, 0600, text_version,
  grant and withdraw, deleted with the user), POST /api/ask behind a browser
  session that refuses credential-shaped input with FindSecret, and an admin
  counter. With the switch off every route answers 404.

Tests use a fake vendor server and assert the exact request body, that
seeded secrets, repo and hive names and logins never leave, and that
consent, limits and the breaker hold.

Closes #19180

Hive-Run: #19180
Hive-Plan: dashboard-ask-ai-help phase 1 (hub backend)
Hive-Spec: dashboard-ask-ai-help#phase-1
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.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 clubanderson 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
#19192 📖 docs: prepare Ask AI dashboard help coverage same files src/docs/design/dashboard-ask-ai-help.md
#19201 📖 Dashboard UI map, docs-site help links and a Settings entry per tab same files src/docs/design/dashboard-ask-ai-help.md
#19200 ✨ ask: hub backend for optional Ask AI help same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
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
#19143 🐛 Reviewer-stated rules: ignore quotes and questions, match more future phrasings, and give the preferences a Settings card same files src/pkg/config/config.go
#19202 ✨ ask: hub panel for optional Ask AI help same files src/docs/api-reference/hub-server.md
src/docs/env-vars.md
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

…oute registration

The Ask AI routes shifted pkg/hub/server.go registration lines, so 34
citations in api-reference/hub-server.md drifted. Rewritten with
src/scripts/check-api-reference-citations.sh --fix; the checker now passes.

Hive-Run: #19180

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Danathar <Danathar@users.noreply.github.com>
@Danathar Danathar changed the title ✨ ask: hub backend for optional Ask AI help (phase 1 of #19177) ✨ ask: hub backend for optional Ask AI help (phase 1) Nov 19, 2026
@Danathar

Copy link
Copy Markdown
Contributor Author

Follow-up on the two failing checks:

  • relative links and anchors resolve: adding the Ask AI routes shifted pkg/hub/server.go registration lines, so 34 citations in api-reference/hub-server.md drifted. Rewritten with check-api-reference-citations.sh --fix (33b5d09); the checker now reports all citations verified.
  • PR Issue: the title carried an issue number (#19177). Removed it; the link to the design issue stays in the PR body.

The other prow notice is only the pending OWNERS approval, which needs a maintainer.


🤖 Generated with Claude Code


🐝 Hive Agent: contributor | SHA: unknown

@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
@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

@Danathar this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the branch conflicts with the base and needs a rebase

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Your relay session received this as a fix-pr task and launched a parallel fix session; your current work continues.

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

Decision needed: @clubanderson should decide which Ask AI phase 1 backend survives, #19200 (pkg/askai) or this one (pkg/ask), since both close #19180 and cannot both merge.

This conflicts with #19200 rather than complementing it. Both implement phase 1 of the Ask AI help backend for #19180 (the body of #19200 says Fixes #19180), and I compared the two diffs' file sets, routes, env constants and bodies, not every line of the roughly 3,000 lines each.

What I verified:

  • Both add src/pkg/config/ask.go, src/pkg/hub/ask.go, and edits to src/pkg/hub/saas.go, server.go and saas_users_admin.go, with the same HIVE_ASK_ENABLED / HIVE_ASK_KAPA_* / HIVE_ASK_MODE env contract.
  • The implementations differ: this PR puts the service in pkg/ask and registers GET /api/saas/admin/ask/stats plus GET/PUT/DELETE /api/ask/consent and POST /api/ask. #19200 puts it in pkg/askai, registers GET /api/ask/status and GET /api/ask/stats, and adds relay-hive env (HIVE_ASK_RELAY_HIVES).
  • #19202 (phase 2 panel) says it builds on #19200 and calls /api/ask/status and /api/ask/stats. Neither route exists in this PR (/api/ask/status appears 0 times in this diff), so the panel cannot sit on this backend without rework.

Suggested survivor: #19200, because the phase 2 panel already targets its routes. Counterpoint for the maintainer: this PR has the fuller CI run (a few test (rest …), test (dashboard …) and coverage jobs failed on this head), while #19200 shows only the early gate jobs since it is also conflicting. Both are CONFLICTING against v5.

If you agree, this one could be closed in favour of #19200. I have not closed anything. I did not assess code quality in this PR in depth.

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

@hivecommons-hive

Copy link
Copy Markdown
Contributor

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

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

This looks like a competing implementation of #19200, not a complement. I read both diffs; neither is reviewed line by line here, only compared.

What I verified:

Differences that matter for the choice:

Flagging for a maintainer: if you agree, one of the two could be closed in favour of the other; I have not closed anything. Which one survives is your call (author, issue linkage and the config-export shape are the real differences). I have not judged the code quality of either beyond the comparison above.

@Danathar

Copy link
Copy Markdown
Contributor Author

Closing in favour of #19200, which clubanderson claimed on #19180 before this relay task was assigned and which #19202 builds on. This was opened by my contributor relay after the claim; nothing here is needed.

@Danathar Danathar closed this Nov 19, 2026
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. 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: hub backend for optional Ask AI help (phase 1 of #19177)

1 participant