Skip to content

✨ sidecar: knowledge advise callback so sidecar runtimes get the mid-task adviser (default off) - #19172

Merged
hivecommons-hive[bot] merged 3 commits into
v5from
feat/sidecar-knowledge-advise
Nov 19, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
v5from
feat/sidecar-knowledge-advise

Conversation

@clubanderson

Copy link
Copy Markdown
Member

What

Slice 5 of the knowledge advisor epic: POST /v1/knowledge/advise on the runtime-callback endpoint, so a sidecar-mode runtime gets the mid-task adviser. It ships default off behind the new knowledge.sidecar_advise knob, per the owner decision on the issue (plumbing only; the rank-mode evidence gate still decides when it is enabled on any live hive, and this PR enables it nowhere).

Behaviour when unconfigured

Unchanged. With knowledge.sidecar_advise false or unset (also requires knowledge.enabled and knowledge.advisor):

  • the route answers 404 not_configured and knowledge_advise is not in /v1/health;
  • the policy snapshot omits knowledge_advise (the JSON is byte-identical), so the runtime never installs the adviser and makes no call;
  • sidecarHost.SetKnowledgeAdviser only holds the chain for the route; nothing is served from it.

Design

Hive side (cmd/hive/knowledge_advise_callback.go, pkg/cruxhost, crux/api/callback):

  • Served only on the existing callback server behind the same bearer token; an unauthenticated call gets the same 401 (tested against another route).
  • Runs the same adviser chain as in-process (phase 1, optionally the ranking decorator), so the hive-wide budget and pacer apply. Candidates still come from PrimeScoped under knowledge.agent_scopes; the request cannot widen scope or pick entries. No model setting or credential crosses, the model reason is never returned.
  • Authz: agent must belong to the calling runtime (status lookup on the sidecar runtime) and kick_at must be that agent's current kick, else 403 and no advice.
  • Limits: one call in flight per agent and at most two evaluations of a scope per kick (429), at most 128 scopes per kick, pane tail over pane_lines is 400, body over 64 KiB is 413, malformed scope (unknown kind or action, absolute or .. path, long key or keywords) is 400.
  • Pane tail and free-text scope fields are redacted again with logscrub.RedactPaneTokens on receipt; an unwanted pane tail is dropped.

Runtime side (crux/hivecap/knowledge.go, crux/cli):

  • hivecap.KnowledgeAdviser implements a new optional crux.KickBoundKnowledgeAdviser (the manager passes the kick identity when the adviser implements it; the in-process adviser is untouched). Async contract unchanged: one in-flight call per agent comes from the manager.
  • Per-agent policy is fetched in the background with a policy_only call (cached 30 s) so the poll tick never waits on the hive; until it arrives, or when the hive is away, the advisor is off.
  • Pane tail is redacted in the runtime before sending. Fail closed: any transport error, non-2xx or malformed body is no advice, one warning per kick.
  • Installed by the policy applier only after a snapshot says the route is on.

Settings: a switch at the top of the Knowledge pipeline section (knowledge.sidecar_advise, YAML hint), saved through the existing pipeline PUT, applies without a restart. Not added to the parity allowlist. static/index.html regenerated from static-src.

Tests

  • Golden: a sidecar manager over the real callback server types exactly the lines an in-process manager types for the same pane fixture, and the hive sees the same scope and redacted pane tail.
  • Handler tests: 401, 403 (agent and kick mismatch, stale kick), 400 (oversize pane tail, malformed scopes), 413, 429 (per-scope, per-kick, in-flight), knob off (route absent, capability not advertised, snapshot flag absent), advice and pane-tail redaction.
  • Runtime client tests: off until advertised, policy cache and refresh, redaction, one warning per kick against an unreachable hive, advice cap, policy applier install-once.
  • Config, cruxhost, callback wire and settings parity tests.

Docs: design/crux.md, crux-serve.md, agent-knowledge-and-memory.md (new Sidecar runtimes section), knowledge-curator.md, operator-reference, settings.md, API reference and OpenAPI for the pipeline route. Changelog fragment added.

Refs #17157

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 18, 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 hanthor 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 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

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
#19063 ✨ PR gate: fail visibly when the Commit statuses grant is missing same files src/pkg/dashboard/static/index.html
#19143 🐛 Reviewer-stated rules: ignore quotes and questions, match more future phrasings, and give the preferences a Settings card same files dashboard/openapi.json
src/docs/settings.md
src/pkg/dashboard/static/index.html

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UI render evidence

Render evidence captured.

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

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.

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Nov 18, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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

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

Why:

  • the branch conflicts with the base and needs a rebase

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.

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

  • remote_code_execution: adds a remote-fetch-and-execute, decoded payload, reverse shell or embedded credential (src/cmd/hive/knowledge_advise_callback_test.go, src/crux/agent/knowledge_advisor_sidecar_test.go, src/crux/hivecap/knowledge_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.

hive/awaiting-ci: rebased onto v5 (one docs conflict in api-reference/knowledge.md, kept both sides). CI pending - sweep will merge when green.


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

Evidence bundle `#19172cbb5426` sha256:6fe8d43e9c2c2048167bac792cc2b0af44488ab5fc7021f6e69a9efde83d920f — download from the dashboard or `hivectl review evidence #19172`.

…task adviser

Add POST /v1/knowledge/advise to the hive's runtime-callback endpoint, off by
default behind knowledge.sidecar_advise.

Hive side: the route runs the same adviser chain the hive runs in-process
(phase 1, optionally wrapped by the ranking pass), behind the same bearer
token as the other /v1 callbacks. It checks that the agent belongs to the
calling runtime and that the kick is the agent's current one (403), allows one
call in flight per agent and two evaluations per scope per kick (429), rejects
a pane tail over pane_lines (400) and a body over 64 KiB (413), and redacts
the pane tail again on receipt. No model setting or credential is sent to the
runtime and the model reason is never returned.

Runtime side: hivecap.KnowledgeAdviser implements the kick-bound adviser seam
over the route, fetches each agent's policy in the background, redacts the
pane tail before sending, fails closed, and logs one warning per kick. The
runtime installs it only when the hive's policy snapshot says the route is on,
so with the knob off nothing changes.

Settings gets a switch at the top of the Knowledge pipeline section, saved
through the pipeline PUT. Docs, OpenAPI and a changelog fragment included.

Refs #17157

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
… sidecar switch help

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…gs parity allowlist

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@hivecommons-hive
hivecommons-hive Bot force-pushed the feat/sidecar-knowledge-advise branch from 94e3355 to cbb5426 Compare November 18, 2026 23:59
@hivecommons-hive
hivecommons-hive Bot merged commit fbf5002 into v5 Nov 19, 2026
93 of 94 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/sidecar-knowledge-advise branch November 19, 2026 00:26
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.

1 participant