From ab34393c070d2f0ee9c4695920b5d34603382615 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 18 Nov 2026 18:12:26 -0500 Subject: [PATCH 1/3] =?UTF-8?q?=E2=9C=A8=20sidecar:=20knowledge=20advise?= =?UTF-8?q?=20callback=20so=20sidecar=20runtimes=20get=20the=20mid-task=20?= =?UTF-8?q?adviser?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../added-17157-sidecar-knowledge-advise.md | 1 + dashboard/openapi.json | 24 +- src/cmd/hive/agent_runtime_sidecar.go | 33 +- src/cmd/hive/knowledge_advise_callback.go | 280 +++++++++ .../hive/knowledge_advise_callback_test.go | 573 ++++++++++++++++++ src/crux/agent/knowledge_advisor.go | 7 +- .../agent/knowledge_advisor_sidecar_test.go | 184 ++++++ src/crux/api/callback/callback.go | 99 +++ src/crux/api/callback/callback_test.go | 213 ++++++- src/crux/api/callback/client.go | 21 +- src/crux/api/callback/server.go | 61 +- src/crux/api/client/client_test.go | 7 +- src/crux/api/runtime.go | 6 +- src/crux/cli/hive_callback.go | 21 +- src/crux/cli/hive_policy_test.go | 71 +++ src/crux/hivecap/hivecap.go | 13 + src/crux/hivecap/knowledge.go | 253 ++++++++ src/crux/hivecap/knowledge_test.go | 402 ++++++++++++ src/crux/knowledge_advice.go | 13 + src/docs/agent-knowledge-and-memory.md | 51 ++ src/docs/api-reference/knowledge.md | 4 +- src/docs/crux-serve.md | 1 + src/docs/design/crux.md | 4 +- src/docs/knowledge-curator.md | 6 +- src/docs/operator-reference/README.md | 3 +- src/docs/settings.md | 2 +- src/pkg/config/knowledge_advisor_test.go | 54 ++ src/pkg/config/knowledge_config.go | 15 + .../config/testdata/agent_runtime_golden.json | 3 +- src/pkg/cruxhost/cruxhost.go | 51 +- src/pkg/cruxhost/cruxhost_test.go | 108 ++++ .../api_config_knowledge_pipeline.go | 15 +- .../knowledge_settings_parity_test.go | 84 +++ .../dashboard/static-src/js/config-state.js | 2 +- .../dashboard/static-src/js/config-tabs.js | 14 +- src/pkg/dashboard/static/index.html | 16 +- 36 files changed, 2665 insertions(+), 50 deletions(-) create mode 100644 changelog.d/added-17157-sidecar-knowledge-advise.md create mode 100644 src/cmd/hive/knowledge_advise_callback.go create mode 100644 src/cmd/hive/knowledge_advise_callback_test.go create mode 100644 src/crux/agent/knowledge_advisor_sidecar_test.go create mode 100644 src/crux/hivecap/knowledge.go create mode 100644 src/crux/hivecap/knowledge_test.go diff --git a/changelog.d/added-17157-sidecar-knowledge-advise.md b/changelog.d/added-17157-sidecar-knowledge-advise.md new file mode 100644 index 0000000000..c50367e8d6 --- /dev/null +++ b/changelog.d/added-17157-sidecar-knowledge-advise.md @@ -0,0 +1 @@ +- New opt-in `knowledge.sidecar_advise` (default `false`, also a switch at the top of Settings, Knowledge, applies without a restart) gives a sidecar-mode runtime the mid-task knowledge advisor through a new `POST /v1/knowledge/advise` route on the runtime-callback endpoint, which until now ran with no adviser at all. The route is served only behind the same bearer token as the other `/v1/*` callbacks and only while the knob, `knowledge.enabled` and `knowledge.advisor` are on; off, it answers `404 not_configured`, the hive does not advertise the `knowledge_advise` capability, and a sidecar runtime behaves exactly as before. The hive runs the adviser chain it runs in-process (phase 1, with the `advisor_llm` ranking pass, its budgets and the hive-wide pacer when configured), so no inference credential or model setting reaches the runtime and the model's reason is never typed. The runtime sends the scope and a pane tail redacted with `RedactPaneTokens` (the hive redacts again); the hive refuses with 403 an agent the calling runtime does not own or a kick that is not the agent's current one, with 429 a second call in flight for an agent or a third evaluation of one scope in a kick, with 400 a pane tail over `pane_lines`, and with 413 a body over 64 KiB. Any failure is no advice, with one warning per kick ([#17157](https://github.com/hivecommons/hive/issues/17157), part of [#17054](https://github.com/hivecommons/hive/issues/17054)). diff --git a/dashboard/openapi.json b/dashboard/openapi.json index f91aba9894..95e1bec11f 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -19341,7 +19341,7 @@ "Knowledge" ], "summary": "Knowledge pipeline settings", - "description": "Returns the scalar knowledge.bead_synthesizer, knowledge.curator, knowledge.code_maps and knowledge.primer settings, plus the read-only engine, vault paths and primer merge strategy. Requires owner role.", + "description": "Returns the scalar knowledge.bead_synthesizer, knowledge.curator, knowledge.code_maps and knowledge.primer settings and knowledge.sidecar_advise, plus the read-only engine, advisor flag, vault paths and primer merge strategy. Requires owner role.", "responses": { "200": { "description": "Knowledge pipeline settings", @@ -19354,6 +19354,14 @@ "type": "string", "description": "Read-only: knowledge.engine" }, + "sidecar_advise": { + "type": "boolean", + "description": "knowledge.sidecar_advise: serve the mid-task knowledge advisor to a sidecar-mode runtime (default false)" + }, + "advisor": { + "type": "boolean", + "description": "Read-only: knowledge.advisor, which sidecar_advise needs" + }, "bead_synthesizer": { "type": "object", "properties": { @@ -19506,7 +19514,7 @@ "Knowledge" ], "summary": "Update knowledge pipeline settings", - "description": "Updates the scalar bead synthesizer, curator, code map and primer settings. Fields are pointer-typed; absent fields are left unchanged and 0 or empty restores the default. Validated with config.ValidateKnowledgePipeline before anything is applied, then persisted and audited as config_knowledge_pipeline. bead_synthesizer.enabled starts or stops the synthesizer at once; every other field applies after a restart. Requires owner role.", + "description": "Updates the scalar bead synthesizer, curator, code map and primer settings and knowledge.sidecar_advise. Fields are pointer-typed; absent fields are left unchanged and 0 or empty restores the default. Validated with config.ValidateKnowledgePipeline before anything is applied, then persisted and audited as config_knowledge_pipeline. bead_synthesizer.enabled and sidecar_advise apply at once; every other field applies after a restart. Requires owner role.", "requestBody": { "required": true, "content": { @@ -19514,6 +19522,10 @@ "schema": { "type": "object", "properties": { + "sidecar_advise": { + "type": "boolean", + "description": "knowledge.sidecar_advise: serve the mid-task knowledge advisor to a sidecar-mode runtime (default false). Applies without a restart." + }, "bead_synthesizer": { "type": "object", "properties": { @@ -19640,6 +19652,14 @@ "type": "string", "description": "Read-only: knowledge.engine" }, + "sidecar_advise": { + "type": "boolean", + "description": "knowledge.sidecar_advise: serve the mid-task knowledge advisor to a sidecar-mode runtime (default false)" + }, + "advisor": { + "type": "boolean", + "description": "Read-only: knowledge.advisor, which sidecar_advise needs" + }, "bead_synthesizer": { "type": "object", "properties": { diff --git a/src/cmd/hive/agent_runtime_sidecar.go b/src/cmd/hive/agent_runtime_sidecar.go index 2f4982c134..0c12cb3dd5 100644 --- a/src/cmd/hive/agent_runtime_sidecar.go +++ b/src/cmd/hive/agent_runtime_sidecar.go @@ -15,6 +15,7 @@ import ( "github.com/hivecommons/hive/crux/effects" "github.com/hivecommons/hive/crux/pushbroker" + "github.com/hivecommons/hive/pkg/config" "github.com/hivecommons/hive/pkg/cruxhost" "github.com/hivecommons/hive/pkg/fleetreport" "github.com/hivecommons/hive/pkg/ioscan" @@ -76,6 +77,11 @@ type sidecarHost struct { mint crux.AgentMintIssuer bobKey func() string bobKeySource func() string + // knowledge is the mid-task adviser chain boot installed + // (hivecommons/hive#17157). It is held, not served: POST + // /v1/knowledge/advise answers from it only while + // knowledge.sidecar_advise is on, and the setter changes nothing else. + knowledge crux.KnowledgeAdviser } var _ hostedRuntime = (*sidecarHost)(nil) @@ -331,12 +337,26 @@ func (h *sidecarHost) SetSandboxMutationBoundary(boundary effects.Boundary) { // the runtime's own process); trajectory events do not depend on it. func (h *sidecarHost) SetSpanStarter(crux.SpanStarter) { h.inProcessOnly("SetSpanStarter") } -// SetKnowledgeAdviser is in-process-only in phase 1 of hivecommons/hive#17052: -// the adviser searches the knowledge store that lives in the hive process. -// A sidecar runtime runs without the mid-task advisor until a callback route -// carries the scope → advice exchange. -func (h *sidecarHost) SetKnowledgeAdviser(crux.KnowledgeAdviser) { - h.inProcessOnly("SetKnowledgeAdviser") +// SetKnowledgeAdviser holds the adviser chain for the hive callback's +// POST /v1/knowledge/advise (hivecommons/hive#17157). The adviser searches the +// knowledge store that lives in the hive process, so the sidecar runtime sends +// the scope across and gets advice lines back; it never holds the chain. The +// route is off unless knowledge.sidecar_advise is set (default false), so with +// the knob off this changes nothing and a sidecar runtime runs without the +// mid-task advisor exactly as before. +func (h *sidecarHost) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { + h.mu.Lock() + h.knowledge = adviser + h.mu.Unlock() + h.callbackCarried("SetKnowledgeAdviser") +} + +// knowledgeAdviser is the chain SetKnowledgeAdviser installed, nil before +// boot has. +func (h *sidecarHost) knowledgeAdviser() crux.KnowledgeAdviser { + h.mu.Lock() + defer h.mu.Unlock() + return h.knowledge } // SetSandboxGitHubReadRelay is in-process-only (#18865): the relay holds the @@ -506,6 +526,7 @@ func (b *boot) hiveCallbackCapabilities() *cruxhost.Capabilities { deps.Mutation = sh deps.Mint = sh deps.Bob = sh.bobCredential + deps.Knowledge = newSidecarKnowledgeAdvise(func() *config.Config { return b.cfg }, sh.knowledgeAdviser, sh.GetStatusFast) } return cruxhost.New(deps) } diff --git a/src/cmd/hive/knowledge_advise_callback.go b/src/cmd/hive/knowledge_advise_callback.go new file mode 100644 index 0000000000..9362e5c063 --- /dev/null +++ b/src/cmd/hive/knowledge_advise_callback.go @@ -0,0 +1,280 @@ +package main + +import ( + "context" + "fmt" + "strings" + "sync" + "time" + "unicode/utf8" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/api/callback" + "github.com/hivecommons/hive/crux/logscrub" + "github.com/hivecommons/hive/pkg/config" +) + +// POST /v1/knowledge/advise (hivecommons/hive#17157, slice 5 of #17054): the +// hive side of the mid-task knowledge advisor for a sidecar runtime. The +// runtime sends the scope an agent just entered (and the redacted pane tail +// when the policy asks for it); the hive runs the same adviser chain it runs +// in-process (phase 1, wrapped by the ranking pass when configured) and sends +// back advice lines plus the delivery policy. Candidates come from the hive's +// own knowledge store under knowledge.agent_scopes; the request cannot widen +// that scope or pick entries, no inference credential or model setting leaves +// the hive, and the runtime types only the advice fields, never a model reason. +// +// The route is served only while knowledge.sidecar_advise is on (default off). +// Off, it answers 404 not_configured and the hive does not advertise it. + +const ( + // knowledgeAdviseMaxEvalsPerScope is the owner's "at most twice per kick" + // (hivecommons/hive#17054, condition 4): a scope is evaluated on first + // sighting and once more on its first edit or next gh command. The + // runtime already behaves that way; the hive refuses a third call for + // one scope in one kick from a runtime that does not. + knowledgeAdviseMaxEvalsPerScope = 2 + // knowledgeAdviseMaxScopesPerKick bounds how many distinct scopes one + // kick may have evaluated, so a misbehaving runtime cannot walk past the + // per-scope limit by inventing keys. + knowledgeAdviseMaxScopesPerKick = 128 + // knowledgeAdviseMaxKeyRunes, knowledgeAdviseMaxPathRunes, + // knowledgeAdviseMaxKeywords and knowledgeAdviseMaxKeywordRunes bound + // the free-text scope fields. A real scope key is at most three path + // segments and a path one relative file path. + knowledgeAdviseMaxKeyRunes = 256 + knowledgeAdviseMaxPathRunes = 512 + knowledgeAdviseMaxKeywords = 16 + knowledgeAdviseMaxKeywordRunes = 64 + // knowledgeAdviseMaxAdvice caps the advice entries one response carries. + knowledgeAdviseMaxAdvice = 8 + // knowledgeScopeKindPath and knowledgeScopeKindGH are the scope kinds the + // runtime produces (crux/agent knowledge_advisor.go). + knowledgeScopeKindPath = "path" + knowledgeScopeKindGH = "gh" +) + +// sidecarKnowledgeAdvise implements cruxhost.KnowledgeAdviseService over the +// adviser the hive installed through SetKnowledgeAdviser. +type sidecarKnowledgeAdvise struct { + cfg func() *config.Config + // adviser is the chain installed on the sidecar host; nil until boot + // installs it, which keeps the route off. + adviser func() crux.KnowledgeAdviser + // status reads one agent from the sidecar runtime: how the hive learns + // that the agent belongs to the calling runtime and which kick it is in. + status func(agent string) (*crux.Process, error) + + mu sync.Mutex + inFlight map[string]bool + kicks map[string]*knowledgeAdviseKick +} + +// knowledgeAdviseKick is what the hive has evaluated for one agent's current +// kick, so the per-scope limit survives across calls. It is replaced when the +// agent's kick changes. +type knowledgeAdviseKick struct { + at time.Time + evals map[string]int +} + +func newSidecarKnowledgeAdvise(cfg func() *config.Config, adviser func() crux.KnowledgeAdviser, status func(string) (*crux.Process, error)) *sidecarKnowledgeAdvise { + return &sidecarKnowledgeAdvise{ + cfg: cfg, + adviser: adviser, + status: status, + inFlight: make(map[string]bool), + kicks: make(map[string]*knowledgeAdviseKick), + } +} + +// Enabled reports whether the route is on: knowledge, the advisor and +// knowledge.sidecar_advise are all set and an adviser is installed. It reads +// the live config, so a reload turns the route on or off. +func (s *sidecarKnowledgeAdvise) Enabled() bool { + return s.cfg().KnowledgeSidecarAdviseEnabled() && s.adviser() != nil +} + +// AdviseKnowledge answers one runtime request. Every refusal is an error the +// callback server maps to a status (ErrForbidden 403, ErrInvalidRequest 400, +// ErrRateLimited 429, ErrNotConfigured 404), and the runtime reads any of them +// as no advice. +func (s *sidecarKnowledgeAdvise) AdviseKnowledge(_ context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + if !s.Enabled() { + return callback.KnowledgeAdviseResponse{}, callback.ErrNotConfigured + } + adviser := s.adviser() + if adviser == nil { + return callback.KnowledgeAdviseResponse{}, callback.ErrNotConfigured + } + if !req.PolicyOnly { + if err := validateKnowledgeAdviseScope(req.Scope); err != nil { + return callback.KnowledgeAdviseResponse{}, err + } + if req.KickAt.IsZero() { + return callback.KnowledgeAdviseResponse{}, fmt.Errorf("%w: kick_at is required", callback.ErrInvalidRequest) + } + } + + // Identity: the agent must belong to the calling runtime and, for an + // evaluation, the kick must be the one the agent is in right now. + proc, err := s.status(req.Agent) + if err != nil || proc == nil { + return callback.KnowledgeAdviseResponse{}, fmt.Errorf("%w: agent is not owned by this runtime", callback.ErrForbidden) + } + if !req.PolicyOnly && (proc.LastKick == nil || !proc.LastKick.Equal(req.KickAt)) { + return callback.KnowledgeAdviseResponse{}, fmt.Errorf("%w: kick is not the agent's current kick", callback.ErrForbidden) + } + + policy := adviser.Policy(req.Agent) + resp := callback.KnowledgeAdviseResponse{Advice: []callback.KnowledgeAdvice{}, Policy: wireKnowledgePolicy(policy)} + if req.PolicyOnly || !policy.Enabled { + return resp, nil + } + + scope, err := cruxKnowledgeScope(req.Scope, resp.Policy) + if err != nil { + return callback.KnowledgeAdviseResponse{}, err + } + release, err := s.begin(req.Agent, req.KickAt, scope.Key) + if err != nil { + return callback.KnowledgeAdviseResponse{}, err + } + defer release() + + for _, adv := range adviser.Advise(req.Agent, scope) { + if adv.Slug == "" { + continue + } + resp.Advice = append(resp.Advice, callback.KnowledgeAdvice{Slug: adv.Slug, Title: adv.Title, Summary: adv.Summary, Ref: adv.Ref}) + if len(resp.Advice) >= knowledgeAdviseMaxAdvice { + break + } + } + return resp, nil +} + +// begin admits one evaluation: at most one call in flight per agent, and at +// most knowledgeAdviseMaxEvalsPerScope evaluations of a scope per kick. The +// returned func ends the in-flight window. Both limits sit in front of the +// adviser chain, so they also bound what reaches the ranking pass and its +// hive-wide budget and pacer. +func (s *sidecarKnowledgeAdvise) begin(agent string, kickAt time.Time, scopeKey string) (func(), error) { + s.mu.Lock() + defer s.mu.Unlock() + if s.inFlight[agent] { + return nil, fmt.Errorf("%w: a call is already in flight for this agent", callback.ErrRateLimited) + } + kick := s.kicks[agent] + if kick == nil || !kick.at.Equal(kickAt) { + kick = &knowledgeAdviseKick{at: kickAt, evals: make(map[string]int)} + s.kicks[agent] = kick + } + used, seen := kick.evals[scopeKey] + if used >= knowledgeAdviseMaxEvalsPerScope { + return nil, fmt.Errorf("%w: this scope was already evaluated %d times in this kick", callback.ErrRateLimited, used) + } + if !seen && len(kick.evals) >= knowledgeAdviseMaxScopesPerKick { + return nil, fmt.Errorf("%w: too many scopes evaluated in this kick", callback.ErrRateLimited) + } + kick.evals[scopeKey] = used + 1 + s.inFlight[agent] = true + return func() { + s.mu.Lock() + defer s.mu.Unlock() + delete(s.inFlight, agent) + }, nil +} + +// wireKnowledgePolicy is the adviser's policy on the wire. A pane tail the +// policy wants always has an explicit length, the same default the runtime +// would apply, so both ends enforce one number. +func wireKnowledgePolicy(p crux.KnowledgeAdvisorPolicy) callback.KnowledgeAdvisorPolicy { + out := callback.KnowledgeAdvisorPolicy{ + Enabled: p.Enabled, + MaxPerKick: p.MaxPerKick, + CooldownMS: int(p.Cooldown / time.Millisecond), + WantsPaneTail: p.WantsPaneTail, + PaneLines: p.PaneLines, + } + if out.WantsPaneTail && out.PaneLines <= 0 { + out.PaneLines = config.DefaultAdvisorLLMPaneLines + } + return out +} + +// validateKnowledgeAdviseScope checks the shape of a scope before anything is +// read from the store: a known kind, a key, bounded text, and a path that is +// relative and stays inside the work tree. Nothing here widens the scope; the +// store still filters by the agent's knowledge.agent_scopes. +func validateKnowledgeAdviseScope(s callback.KnowledgeScope) error { + switch s.Kind { + case knowledgeScopeKindPath, knowledgeScopeKindGH: + default: + return fmt.Errorf("%w: scope kind must be %q or %q", callback.ErrInvalidRequest, knowledgeScopeKindPath, knowledgeScopeKindGH) + } + switch s.Action { + case "", crux.KnowledgeActionRead, crux.KnowledgeActionEdit, crux.KnowledgeActionRun: + default: + return fmt.Errorf("%w: unknown scope action", callback.ErrInvalidRequest) + } + if s.Key == "" || utf8.RuneCountInString(s.Key) > knowledgeAdviseMaxKeyRunes || strings.ContainsAny(s.Key, "\r\n\x00") { + return fmt.Errorf("%w: scope key is empty, too long or multi-line", callback.ErrInvalidRequest) + } + if utf8.RuneCountInString(s.Path) > knowledgeAdviseMaxPathRunes || strings.ContainsAny(s.Path, "\r\n\x00") || + strings.HasPrefix(s.Path, "/") || strings.HasPrefix(s.Path, "~") || hasParentSegment(s.Path) { + return fmt.Errorf("%w: scope path must be a short relative path inside the work tree", callback.ErrInvalidRequest) + } + if len(s.Keywords) > knowledgeAdviseMaxKeywords { + return fmt.Errorf("%w: too many scope keywords", callback.ErrInvalidRequest) + } + for _, kw := range s.Keywords { + if utf8.RuneCountInString(kw) > knowledgeAdviseMaxKeywordRunes || strings.ContainsAny(kw, "\r\n\x00") { + return fmt.Errorf("%w: scope keyword is too long or multi-line", callback.ErrInvalidRequest) + } + } + return nil +} + +func hasParentSegment(path string) bool { + for _, seg := range strings.Split(path, "/") { + if seg == ".." { + return true + } + } + return false +} + +// cruxKnowledgeScope turns a validated wire scope into the in-process one. The +// pane tail is dropped when the policy does not want one, rejected (400) when +// it is longer than the policy's pane_lines, and redacted again here, so the +// hive never trusts the runtime's own scrub. Free-text fields get the same +// redaction before they reach a log line or the model prompt. +func cruxKnowledgeScope(w callback.KnowledgeScope, policy callback.KnowledgeAdvisorPolicy) (crux.KnowledgeScope, error) { + sc := crux.KnowledgeScope{ + Kind: w.Kind, + Key: logscrub.RedactPaneTokens(w.Key), + Path: logscrub.RedactPaneTokens(w.Path), + Action: w.Action, + } + for _, kw := range w.Keywords { + sc.Keywords = append(sc.Keywords, logscrub.RedactPaneTokens(kw)) + } + if policy.WantsPaneTail && w.PaneTail != "" { + if n := knowledgePaneLineCount(w.PaneTail); n > policy.PaneLines { + return crux.KnowledgeScope{}, fmt.Errorf("%w: pane tail has %d lines, pane_lines is %d", callback.ErrInvalidRequest, n, policy.PaneLines) + } + sc.PaneTail = logscrub.RedactPaneTokens(w.PaneTail) + } + return sc, nil +} + +// knowledgePaneLineCount counts lines the way the runtime cuts a pane tail: +// trailing newlines do not count. +func knowledgePaneLineCount(tail string) int { + tail = strings.TrimRight(tail, "\n") + if tail == "" { + return 0 + } + return strings.Count(tail, "\n") + 1 +} diff --git a/src/cmd/hive/knowledge_advise_callback_test.go b/src/cmd/hive/knowledge_advise_callback_test.go new file mode 100644 index 0000000000..ba3d7e2d2e --- /dev/null +++ b/src/cmd/hive/knowledge_advise_callback_test.go @@ -0,0 +1,573 @@ +package main + +import ( + "context" + "errors" + "fmt" + "log/slog" + "net/http" + "net/http/httptest" + "slices" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/api" + "github.com/hivecommons/hive/crux/api/callback" + "github.com/hivecommons/hive/crux/cruxtest" + "github.com/hivecommons/hive/pkg/config" +) + +// POST /v1/knowledge/advise (hivecommons/hive#17157): the hive side of the +// sidecar knowledge adviser. These tests drive the real callback server over +// HTTP against the sidecar host's capability set, with a recording adviser +// standing in for the chain boot installs. + +const ( + adviseTestAgent = "developer" + adviseTestToken = "advise-test-bearer" + adviseTestTail = "first line\nsecond line\ntoken ghp_abcdefghijklmnopqrstuvwxyz0123456789 here\n" +) + +// recordingKnowledgeAdviser is the adviser chain: it records every scope it is +// asked about and answers a fixed policy and advice list. When release is set +// Advise blocks on it after signalling entered. +type recordingKnowledgeAdviser struct { + mu sync.Mutex + policy crux.KnowledgeAdvisorPolicy + advice []crux.KnowledgeAdvice + scopes []crux.KnowledgeScope + entered chan struct{} + release chan struct{} +} + +func (r *recordingKnowledgeAdviser) Policy(string) crux.KnowledgeAdvisorPolicy { return r.policy } + +func (r *recordingKnowledgeAdviser) Advise(_ string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + r.mu.Lock() + r.scopes = append(r.scopes, scope) + r.mu.Unlock() + if r.release != nil { + r.entered <- struct{}{} + <-r.release + } + return r.advice +} + +func (r *recordingKnowledgeAdviser) asked() []crux.KnowledgeScope { + r.mu.Lock() + defer r.mu.Unlock() + return slices.Clone(r.scopes) +} + +type adviseHarness struct { + t *testing.T + url string + client *callback.Client + adviser *recordingKnowledgeAdviser + rt *cruxtest.Recorder + kickAt time.Time +} + +// newAdviseHarness serves the sidecar host's callback capabilities with +// knowledge.sidecar_advise set to sidecarAdvise. The runtime owns one agent, +// developer, in the kick that started at h.kickAt. +func newAdviseHarness(t *testing.T, sidecarAdvise bool, policy crux.KnowledgeAdvisorPolicy) *adviseHarness { + t.Helper() + rec := cruxtest.NewRecorder() + kickAt := time.Date(2026, 11, 18, 12, 0, 0, 123456789, time.UTC) + rec.Add(adviseTestAgent, "id-1", crux.StateRunning).LastKick = &kickAt + host := newSidecarHost(&sidecarRuntimeFake{Runtime: rec}, slog.New(slog.DiscardHandler)) + adviser := &recordingKnowledgeAdviser{ + policy: policy, + advice: []crux.KnowledgeAdvice{ + {Slug: "agent-manager-lock", Title: "Manager lock order", Summary: "Take m.mu before a.mu.", Ref: "knowledge entry agent-manager-lock"}, + {Slug: "", Title: "ignored: no slug"}, + }, + } + host.SetKnowledgeAdviser(adviser) + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, SidecarAdvise: sidecarAdvise}} + caps := (&boot{agentMgr: host, cfg: cfg}).hiveCallbackCapabilities() + srv := httptest.NewServer(callback.NewServer(caps, adviseTestToken).Handler()) + t.Cleanup(srv.Close) + client, err := callback.NewClient(srv.URL, adviseTestToken) + if err != nil { + t.Fatal(err) + } + return &adviseHarness{t: t, url: srv.URL, client: client, adviser: adviser, rt: rec, kickAt: kickAt} +} + +func (h *adviseHarness) request(key string) callback.KnowledgeAdviseRequest { + return callback.KnowledgeAdviseRequest{ + Agent: adviseTestAgent, + KickAt: h.kickAt, + Scope: callback.KnowledgeScope{ + Kind: "path", Key: key, Path: key + "/manager.go", Keywords: []string{"crux", "agent"}, Action: crux.KnowledgeActionEdit, + }, + } +} + +// startNewKick moves the agent into a kick that started at a later time. +func (h *adviseHarness) startNewKick() time.Time { + h.t.Helper() + next := h.kickAt.Add(time.Minute) + h.rt.Procs[adviseTestAgent].LastKick = &next + return next +} + +func statusOf(t *testing.T, err error) int { + t.Helper() + var se *api.StatusError + if !errors.As(err, &se) { + t.Fatalf("error %v is not an *api.StatusError", err) + } + return se.Status +} + +func rankPolicy() crux.KnowledgeAdvisorPolicy { + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 3, Cooldown: 90 * time.Second, WantsPaneTail: true, PaneLines: 4} +} + +func TestSidecarKnowledgeAdvise_KnobOffIsInvisible(t *testing.T) { + h := newAdviseHarness(t, false, rankPolicy()) + ctx := context.Background() + + health, err := h.client.Health(ctx) + if err != nil { + t.Fatal(err) + } + if slices.Contains(health.Capabilities, callback.CapabilityKnowledgeAdvise) { + t.Errorf("knob off advertises the capability: %v", health.Capabilities) + } + pol, err := h.client.Policy(ctx) + if err != nil { + t.Fatal(err) + } + if pol.KnowledgeAdvise { + t.Error("knob off: the policy snapshot says the route is on") + } + _, err = h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")) + if !errors.Is(err, callback.ErrNotConfigured) { + t.Fatalf("knob off: err = %v, want not_configured", err) + } + if _, err = h.client.AdviseKnowledge(ctx, callback.KnowledgeAdviseRequest{Agent: adviseTestAgent, PolicyOnly: true}); !errors.Is(err, callback.ErrNotConfigured) { + t.Fatalf("knob off, policy only: err = %v, want not_configured", err) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("knob off reached the adviser %d times", n) + } +} + +func TestSidecarKnowledgeAdvise_NeedsAdvisorAndKnowledge(t *testing.T) { + for name, mutate := range map[string]func(*config.KnowledgeConfig){ + "advisor off": func(k *config.KnowledgeConfig) { k.Advisor = false }, + "knowledge off": func(k *config.KnowledgeConfig) { k.Enabled = false }, + } { + t.Run(name, func(t *testing.T) { + svc := newSidecarKnowledgeAdvise( + func() *config.Config { + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, SidecarAdvise: true}} + mutate(&cfg.Knowledge) + return cfg + }, + func() crux.KnowledgeAdviser { return &recordingKnowledgeAdviser{} }, + func(string) (*crux.Process, error) { return &crux.Process{}, nil }, + ) + if svc.Enabled() { + t.Fatal("route is on without the advisor") + } + }) + } + noAdviser := newSidecarKnowledgeAdvise( + func() *config.Config { + return &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, SidecarAdvise: true}} + }, + func() crux.KnowledgeAdviser { return nil }, + nil, + ) + if noAdviser.Enabled() { + t.Fatal("route is on before boot installed an adviser") + } + nilCfg := newSidecarKnowledgeAdvise(func() *config.Config { return nil }, func() crux.KnowledgeAdviser { return &recordingKnowledgeAdviser{} }, nil) + if nilCfg.Enabled() { + t.Fatal("route is on with no config") + } +} + +func TestSidecarKnowledgeAdvise_AdvertisedWhenOn(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + ctx := context.Background() + health, err := h.client.Health(ctx) + if err != nil { + t.Fatal(err) + } + if !slices.Contains(health.Capabilities, callback.CapabilityKnowledgeAdvise) { + t.Errorf("capability not advertised: %v", health.Capabilities) + } + pol, err := h.client.Policy(ctx) + if err != nil { + t.Fatal(err) + } + if !pol.KnowledgeAdvise { + t.Error("policy snapshot does not say the route is on") + } +} + +// The route refuses an unauthenticated call with the status every other +// callback route gives, and never reaches the adviser. +func TestSidecarKnowledgeAdvise_RefusesUnauthenticated(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + post := func(path, auth string) int { + req, err := http.NewRequest(http.MethodPost, h.url+path, strings.NewReader(`{"agent":"developer"}`)) + if err != nil { + t.Fatal(err) + } + if auth != "" { + req.Header.Set("Authorization", auth) + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatal(err) + } + _ = resp.Body.Close() + return resp.StatusCode + } + want := post(callback.PathUsage, "") + for _, auth := range []string{"", "Bearer wrong", "Basic " + adviseTestToken} { + if got := post(callback.PathKnowledgeAdvise, auth); got != http.StatusUnauthorized || got != want { + t.Errorf("auth %q: status %d, other callbacks give %d, want %d", auth, got, want, http.StatusUnauthorized) + } + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("unauthenticated calls reached the adviser %d times", n) + } +} + +func TestSidecarKnowledgeAdvise_ServesAdviceAndRedactsPaneTail(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + req := h.request("src/crux/agent") + req.Scope.PaneTail = adviseTestTail + resp, err := h.client.AdviseKnowledge(context.Background(), req) + if err != nil { + t.Fatal(err) + } + if len(resp.Advice) != 1 || resp.Advice[0].Slug != "agent-manager-lock" || resp.Advice[0].Title != "Manager lock order" || + resp.Advice[0].Summary != "Take m.mu before a.mu." || resp.Advice[0].Ref != "knowledge entry agent-manager-lock" { + t.Fatalf("advice = %+v (an entry with no slug must be dropped)", resp.Advice) + } + want := callback.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 3, CooldownMS: 90000, WantsPaneTail: true, PaneLines: 4} + if resp.Policy != want { + t.Errorf("policy = %+v, want %+v", resp.Policy, want) + } + asked := h.adviser.asked() + if len(asked) != 1 { + t.Fatalf("adviser asked %d times", len(asked)) + } + got := asked[0] + if got.Key != "src/crux/agent" || got.Path != "src/crux/agent/manager.go" || got.Action != crux.KnowledgeActionEdit || !slices.Equal(got.Keywords, []string{"crux", "agent"}) { + t.Errorf("scope = %+v", got) + } + if strings.Contains(got.PaneTail, "ghp_abcdefghijklmnopqrstuvwxyz") || !strings.Contains(got.PaneTail, "ghp_abc***") { + t.Errorf("the hive did not scrub the pane tail on receipt: %q", got.PaneTail) + } +} + +// A wanted pane tail longer than pane_lines is a 400 and nothing is evaluated. +func TestSidecarKnowledgeAdvise_RejectsOversizePaneTail(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + req := h.request("src/crux/agent") + req.Scope.PaneTail = strings.Repeat("line\n", 5) // pane_lines is 4 + _, err := h.client.AdviseKnowledge(context.Background(), req) + if got := statusOf(t, err); got != http.StatusBadRequest { + t.Fatalf("status = %d, want 400", got) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("an oversize request reached the adviser %d times", n) + } + // Exactly pane_lines lines, trailing newline and all, is fine. + req.Scope.PaneTail = strings.Repeat("line\n", 4) + if _, err := h.client.AdviseKnowledge(context.Background(), req); err != nil { + t.Fatalf("pane_lines lines rejected: %v", err) + } +} + +// With no pane tail wanted, none crosses to the adviser. +func TestSidecarKnowledgeAdvise_DropsUnwantedPaneTail(t *testing.T) { + policy := rankPolicy() + policy.WantsPaneTail = false + h := newAdviseHarness(t, true, policy) + req := h.request("src/crux/agent") + req.Scope.PaneTail = adviseTestTail + if _, err := h.client.AdviseKnowledge(context.Background(), req); err != nil { + t.Fatal(err) + } + if asked := h.adviser.asked(); len(asked) != 1 || asked[0].PaneTail != "" { + t.Fatalf("scope = %+v, want no pane tail", asked) + } +} + +func TestSidecarKnowledgeAdvise_RejectsOversizeBody(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + body := `{"agent":"developer","scope":{"kind":"path","key":"a","pane_tail":"` + strings.Repeat("x", 80<<10) + `"}}` + req, err := http.NewRequest(http.MethodPost, h.url+callback.PathKnowledgeAdvise, strings.NewReader(body)) + if err != nil { + t.Fatal(err) + } + req.Header.Set("Authorization", "Bearer "+adviseTestToken) + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatal(err) + } + _ = resp.Body.Close() + if resp.StatusCode != http.StatusRequestEntityTooLarge { + t.Fatalf("status = %d, want 413", resp.StatusCode) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("an oversize body reached the adviser %d times", n) + } +} + +// The agent must belong to the calling runtime and the kick must be its +// current one; anything else is 403 and no advice. +func TestSidecarKnowledgeAdvise_ChecksAgentAndKickIdentity(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + ctx := context.Background() + + req := h.request("src/crux/agent") + req.Agent = "someone-elses-agent" + if _, err := h.client.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrForbidden) { + t.Errorf("unknown agent: err = %v, want forbidden", err) + } + if _, err := h.client.AdviseKnowledge(ctx, callback.KnowledgeAdviseRequest{Agent: "someone-elses-agent", PolicyOnly: true}); !errors.Is(err, callback.ErrForbidden) { + t.Errorf("unknown agent, policy only: err = %v, want forbidden", err) + } + req = h.request("src/crux/agent") + req.KickAt = h.kickAt.Add(-time.Hour) + if _, err := h.client.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrForbidden) { + t.Errorf("stale kick: err = %v, want forbidden", err) + } + req.KickAt = time.Time{} + if _, err := h.client.AdviseKnowledge(ctx, req); statusOf(t, err) != http.StatusBadRequest { + t.Errorf("missing kick: err = %v, want 400", err) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("identity failures reached the adviser %d times", n) + } + + // The same call is fine for the current kick, and refused once the agent + // has moved on to the next one. + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")); err != nil { + t.Fatalf("current kick refused: %v", err) + } + h.startNewKick() + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")); !errors.Is(err, callback.ErrForbidden) { + t.Errorf("previous kick after the agent moved on: err = %v, want forbidden", err) + } +} + +func TestSidecarKnowledgeAdvise_RejectsMalformedScopes(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + long := strings.Repeat("a", knowledgeAdviseMaxKeyRunes+1) + for name, mutate := range map[string]func(*callback.KnowledgeScope){ + "unknown kind": func(s *callback.KnowledgeScope) { s.Kind = "url" }, + "empty key": func(s *callback.KnowledgeScope) { s.Key = "" }, + "long key": func(s *callback.KnowledgeScope) { s.Key = long }, + "multi-line key": func(s *callback.KnowledgeScope) { s.Key = "a\nb" }, + "absolute path": func(s *callback.KnowledgeScope) { s.Path = "/etc/passwd" }, + "home path": func(s *callback.KnowledgeScope) { s.Path = "~/.ssh/id_rsa" }, + "parent path": func(s *callback.KnowledgeScope) { s.Path = "src/../../secrets/key.pem" }, + "unknown action": func(s *callback.KnowledgeScope) { s.Action = "delete" }, + "too many keywords": func(s *callback.KnowledgeScope) { s.Keywords = make([]string, knowledgeAdviseMaxKeywords+1) }, + "long keyword": func(s *callback.KnowledgeScope) { + s.Keywords = []string{strings.Repeat("k", knowledgeAdviseMaxKeywordRunes+1)} + }, + } { + t.Run(name, func(t *testing.T) { + req := h.request("src/crux/agent") + mutate(&req.Scope) + _, err := h.client.AdviseKnowledge(context.Background(), req) + if got := statusOf(t, err); got != http.StatusBadRequest { + t.Fatalf("status = %d, want 400", got) + } + }) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("malformed scopes reached the adviser %d times", n) + } +} + +func TestSidecarKnowledgeAdvise_PolicyOnlyEvaluatesNothing(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + // No kick and no scope: a policy request needs neither. + resp, err := h.client.AdviseKnowledge(context.Background(), callback.KnowledgeAdviseRequest{Agent: adviseTestAgent, PolicyOnly: true}) + if err != nil { + t.Fatal(err) + } + if len(resp.Advice) != 0 || !resp.Policy.Enabled || !resp.Policy.WantsPaneTail || resp.Policy.PaneLines != 4 { + t.Fatalf("policy-only response = %+v", resp) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("a policy request evaluated %d scopes", n) + } +} + +// A pane tail wanted without a length gets the one default both ends use. +func TestSidecarKnowledgeAdvise_PolicyDefaultsPaneLines(t *testing.T) { + h := newAdviseHarness(t, true, crux.KnowledgeAdvisorPolicy{Enabled: true, WantsPaneTail: true}) + resp, err := h.client.AdviseKnowledge(context.Background(), callback.KnowledgeAdviseRequest{Agent: adviseTestAgent, PolicyOnly: true}) + if err != nil { + t.Fatal(err) + } + if resp.Policy.PaneLines != config.DefaultAdvisorLLMPaneLines { + t.Fatalf("pane_lines = %d, want %d", resp.Policy.PaneLines, config.DefaultAdvisorLLMPaneLines) + } +} + +// A policy that is off for the agent (excluded, or the advisor off) means no +// evaluation and no advice, with the policy saying so. +func TestSidecarKnowledgeAdvise_DisabledPolicyGivesNoAdvice(t *testing.T) { + h := newAdviseHarness(t, true, crux.KnowledgeAdvisorPolicy{}) + resp, err := h.client.AdviseKnowledge(context.Background(), h.request("src/crux/agent")) + if err != nil { + t.Fatal(err) + } + if len(resp.Advice) != 0 || resp.Policy.Enabled { + t.Fatalf("response = %+v", resp) + } + if n := len(h.adviser.asked()); n != 0 { + t.Fatalf("a disabled agent reached the adviser %d times", n) + } +} + +// A scope is evaluated at most twice per kick; a new kick starts over; other +// scopes are unaffected. +func TestSidecarKnowledgeAdvise_LimitsEvaluationsPerScopePerKick(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + ctx := context.Background() + for i := 0; i < knowledgeAdviseMaxEvalsPerScope; i++ { + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")); err != nil { + t.Fatalf("evaluation %d refused: %v", i+1, err) + } + } + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")); !errors.Is(err, callback.ErrRateLimited) { + t.Fatalf("third evaluation: err = %v, want rate_limited", err) + } + if n := len(h.adviser.asked()); n != knowledgeAdviseMaxEvalsPerScope { + t.Fatalf("adviser asked %d times, want %d", n, knowledgeAdviseMaxEvalsPerScope) + } + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/pkg/config")); err != nil { + t.Fatalf("another scope refused: %v", err) + } + next := h.startNewKick() + req := h.request("src/crux/agent") + req.KickAt = next + if _, err := h.client.AdviseKnowledge(ctx, req); err != nil { + t.Fatalf("new kick refused: %v", err) + } +} + +func TestSidecarKnowledgeAdvise_LimitsScopesPerKick(t *testing.T) { + policy := rankPolicy() + svc := newSidecarKnowledgeAdvise( + func() *config.Config { + return &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, SidecarAdvise: true}} + }, + func() crux.KnowledgeAdviser { return &recordingKnowledgeAdviser{policy: policy} }, + func(string) (*crux.Process, error) { + kick := time.Unix(1, 0) + return &crux.Process{LastKick: &kick}, nil + }, + ) + req := callback.KnowledgeAdviseRequest{Agent: adviseTestAgent, KickAt: time.Unix(1, 0), Scope: callback.KnowledgeScope{Kind: "gh", Key: "gh:pr"}} + for i := 0; i < knowledgeAdviseMaxScopesPerKick; i++ { + req.Scope.Key = fmt.Sprintf("scope-%d", i) + if _, err := svc.AdviseKnowledge(context.Background(), req); err != nil { + t.Fatalf("scope %d refused: %v", i, err) + } + } + req.Scope.Key = "one-scope-too-many" + if _, err := svc.AdviseKnowledge(context.Background(), req); !errors.Is(err, callback.ErrRateLimited) { + t.Fatalf("err = %v, want rate_limited", err) + } +} + +// One call in flight per agent: a second, whatever its scope, is refused while +// the first runs, and goes through once it finishes. +func TestSidecarKnowledgeAdvise_OneCallInFlightPerAgent(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + h.adviser.entered = make(chan struct{}, 1) + h.adviser.release = make(chan struct{}) + ctx := context.Background() + + done := make(chan error, 1) + go func() { + _, err := h.client.AdviseKnowledge(ctx, h.request("src/crux/agent")) + done <- err + }() + select { + case <-h.adviser.entered: + case <-time.After(5 * time.Second): + t.Fatal("first call never reached the adviser") + } + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/pkg/config")); !errors.Is(err, callback.ErrRateLimited) { + t.Fatalf("second call while one is in flight: err = %v, want rate_limited", err) + } + close(h.adviser.release) + if err := <-done; err != nil { + t.Fatalf("first call: %v", err) + } + if _, err := h.client.AdviseKnowledge(ctx, h.request("src/pkg/config")); err != nil { + t.Fatalf("call after the first finished: %v", err) + } + // The refused call never counted as an evaluation of its scope. + if n := len(h.adviser.asked()); n != 2 { + t.Fatalf("adviser asked %d times, want 2", n) + } +} + +func TestSidecarKnowledgeAdvise_CapsAdvicePerResponse(t *testing.T) { + h := newAdviseHarness(t, true, rankPolicy()) + var many []crux.KnowledgeAdvice + for i := 0; i < knowledgeAdviseMaxAdvice+5; i++ { + many = append(many, crux.KnowledgeAdvice{Slug: strings.Repeat("s", i+1), Title: "t"}) + } + h.adviser.advice = many + resp, err := h.client.AdviseKnowledge(context.Background(), h.request("src/crux/agent")) + if err != nil { + t.Fatal(err) + } + if len(resp.Advice) != knowledgeAdviseMaxAdvice { + t.Fatalf("advice entries = %d, want %d", len(resp.Advice), knowledgeAdviseMaxAdvice) + } +} + +func TestKnowledgePaneLineCount(t *testing.T) { + for _, tt := range []struct { + in string + want int + }{ + {"", 0}, {"\n\n", 0}, {"a", 1}, {"a\n", 1}, {"a\nb", 2}, {"a\nb\n", 2}, {"a\n\nb", 3}, + } { + if got := knowledgePaneLineCount(tt.in); got != tt.want { + t.Errorf("knowledgePaneLineCount(%q) = %d, want %d", tt.in, got, tt.want) + } + } +} + +// Free-text scope fields are redacted too, so a token-shaped path segment +// never reaches a log line or the model prompt. +func TestCruxKnowledgeScope_RedactsFreeText(t *testing.T) { + token := "ghp_abcdefghijklmnopqrstuvwxyz0123456789" + sc, err := cruxKnowledgeScope(callback.KnowledgeScope{ + Kind: "path", Key: "src/" + token, Path: "src/" + token + "/a.go", Keywords: []string{token}, + }, callback.KnowledgeAdvisorPolicy{}) + if err != nil { + t.Fatal(err) + } + joined := sc.Key + sc.Path + strings.Join(sc.Keywords, ",") + if strings.Contains(joined, token) { + t.Fatalf("token survived: %s", joined) + } +} diff --git a/src/crux/agent/knowledge_advisor.go b/src/crux/agent/knowledge_advisor.go index 5358df223d..683f3ab7e8 100644 --- a/src/crux/agent/knowledge_advisor.go +++ b/src/crux/agent/knowledge_advisor.go @@ -356,7 +356,12 @@ func (ka *knowledgeAdvisor) dispatch(name string, st *knowledgeKickState, scroll // made (kickAt, from agent.LastKick) is no longer the current one. func (ka *knowledgeAdvisor) advise(name string, kickAt time.Time, scope crux.KnowledgeScope, done chan struct{}) { defer close(done) - found := ka.adviser.Advise(name, scope) + var found []crux.KnowledgeAdvice + if bound, ok := ka.adviser.(crux.KickBoundKnowledgeAdviser); ok { + found = bound.AdviseForKick(name, kickAt, scope) + } else { + found = ka.adviser.Advise(name, scope) + } ka.mu.Lock() defer ka.mu.Unlock() diff --git a/src/crux/agent/knowledge_advisor_sidecar_test.go b/src/crux/agent/knowledge_advisor_sidecar_test.go new file mode 100644 index 0000000000..5e329229cc --- /dev/null +++ b/src/crux/agent/knowledge_advisor_sidecar_test.go @@ -0,0 +1,184 @@ +package agent + +import ( + "context" + "net/http/httptest" + "reflect" + "strings" + "sync" + "testing" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/api/callback" + "github.com/hivecommons/hive/crux/hivecap" + "github.com/hivecommons/hive/crux/internal/testutil" +) + +// Golden test for the sidecar knowledge adviser (hivecommons/hive#17157): a +// manager whose adviser is the hivecap one, calling POST /v1/knowledge/advise +// on a hive that runs the same chain in-process, types exactly the lines an +// in-process manager types for the same pane fixture, and the hive sees the +// same scope, pane tail included, the in-process adviser sees. + +const sidecarGoldenToken = "ghp_abcdefghijklmnopqrstuvwxyz0123456789" + +// goldenHive is the hive side of the route over an in-process adviser. Only +// the knowledge capability is served; the embedded nil Capabilities is never +// called. +type goldenHive struct { + callback.Capabilities + adviser crux.KnowledgeAdviser + + mu sync.Mutex + requests []callback.KnowledgeAdviseRequest + scopes []crux.KnowledgeScope +} + +func (h *goldenHive) Configured(capability string) bool { + return capability == callback.CapabilityKnowledgeAdvise +} + +func (h *goldenHive) AdviseKnowledge(_ context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + h.mu.Lock() + defer h.mu.Unlock() + pol := h.adviser.Policy(req.Agent) + resp := callback.KnowledgeAdviseResponse{ + Advice: []callback.KnowledgeAdvice{}, + Policy: callback.KnowledgeAdvisorPolicy{ + Enabled: pol.Enabled, MaxPerKick: pol.MaxPerKick, CooldownMS: int(pol.Cooldown / time.Millisecond), + WantsPaneTail: pol.WantsPaneTail, PaneLines: pol.PaneLines, + }, + } + if req.PolicyOnly { + return resp, nil + } + h.requests = append(h.requests, req) + scope := crux.KnowledgeScope{ + Kind: req.Scope.Kind, Key: req.Scope.Key, Path: req.Scope.Path, Keywords: req.Scope.Keywords, + Action: req.Scope.Action, PaneTail: req.Scope.PaneTail, + } + h.scopes = append(h.scopes, scope) + for _, a := range h.adviser.Advise(req.Agent, scope) { + resp.Advice = append(resp.Advice, callback.KnowledgeAdvice{Slug: a.Slug, Title: a.Title, Summary: a.Summary, Ref: a.Ref}) + } + return resp, nil +} + +func (h *goldenHive) seen() ([]callback.KnowledgeAdviseRequest, []crux.KnowledgeScope) { + h.mu.Lock() + defer h.mu.Unlock() + return append([]callback.KnowledgeAdviseRequest(nil), h.requests...), append([]crux.KnowledgeScope(nil), h.scopes...) +} + +func goldenAdviser() *fakeAdviser { + return &fakeAdviser{ + policy: crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, Cooldown: time.Minute, WantsPaneTail: true, PaneLines: 6}, + byKey: map[string][]crux.KnowledgeAdvice{ + "src/scripts": { + {Slug: "scripts-tree", Title: "Re-pin TRUSTED_SCRIPTS_TREE", Summary: "Any src/scripts edit must re-pin the tree.", Ref: "knowledge entry scripts-tree"}, + {Slug: "scripts-shellcheck", Title: "Shellcheck gate", Summary: "Scripts run under shellcheck in CI."}, + }, + }, + } +} + +// goldenPane is the fixture: scrollback with work from before the kick, then a +// new scope entered with an edit and a token in the tail. +func goldenScrollback() (baseline, entered string) { + baseline = "āŗ Read(src/crux/agent/manager.go)" + entered = baseline + "\n$ export GH_TOKEN=" + sidecarGoldenToken + "\nāŗ Edit(src/scripts/ci.sh)" + return baseline, entered +} + +// driveGolden runs the baseline tick and then ticks the entered pane until a +// line is typed (a networked adviser answers on a later tick when it is slower +// than the grace period). +func driveGolden(t *testing.T, adviser crux.KnowledgeAdviser) []string { + t.Helper() + m, a, typed := advisorManager(t, adviser) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + // Let a policy that is fetched in the background arrive before the first + // tick: the tick that baselines the pane must already see it enabled. + testutil.Eventually(t, 5*time.Second, func() bool { return adviser.Policy(a.Name).Enabled }, "adviser policy never became enabled") + baseline, entered := goldenScrollback() + m.adviseKnowledge(a, baseline, workingPane) + testutil.Eventually(t, 5*time.Second, func() bool { + m.adviseKnowledge(a, entered, workingPane) + return len(*typed) > 0 + }, "no advice line was typed") + return *typed +} + +func TestSidecarAdviserDeliversTheSameLinesAsInProcess(t *testing.T) { + inProcess := goldenAdviser() + wantLines := driveGolden(t, inProcess) + + hiveAdviser := goldenAdviser() + hive := &goldenHive{adviser: hiveAdviser} + srv := httptest.NewServer(callback.NewServer(hive, "golden-token").Handler()) + t.Cleanup(srv.Close) + client, err := callback.NewClient(srv.URL, "golden-token") + if err != nil { + t.Fatal(err) + } + sidecar := hivecap.NewKnowledgeAdviser(client, func() bool { return true }, 0) + gotLines := driveGolden(t, sidecar) + + if len(wantLines) != 1 || !strings.HasPrefix(wantLines[0], "šŸ“š Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — Any src/scripts edit") { + t.Fatalf("in-process lines = %v", wantLines) + } + if !reflect.DeepEqual(gotLines, wantLines) { + t.Fatalf("sidecar typed %v, in-process typed %v", gotLines, wantLines) + } + + // The hive saw the scope the in-process adviser saw, pane tail and all, + // with no raw token. + requests, scopes := hive.seen() + if len(scopes) != 1 || len(inProcess.scopes) != 1 { + t.Fatalf("hive saw %d scopes, in-process adviser %d", len(scopes), len(inProcess.scopes)) + } + if !reflect.DeepEqual(scopes[0], inProcess.scopes[0]) { + t.Errorf("hive scope = %+v\nin-process scope = %+v", scopes[0], inProcess.scopes[0]) + } + if scopes[0].Action != crux.KnowledgeActionEdit || scopes[0].Key != "src/scripts" || scopes[0].PaneTail == "" { + t.Errorf("scope = %+v", scopes[0]) + } + if strings.Contains(scopes[0].PaneTail, sidecarGoldenToken) || !strings.Contains(scopes[0].PaneTail, "ghp_abc***") { + t.Errorf("pane tail not redacted: %q", scopes[0].PaneTail) + } + if requests[0].Agent != "developer" || requests[0].KickAt.IsZero() { + t.Errorf("request identity = %+v", requests[0]) + } +} + +// With the hive unreachable nothing is typed: the policy never arrives, so the +// advisor stays off and no pane is parsed (the per-kick warning for a call that +// fails mid-kick is covered in crux/hivecap). +func TestSidecarAdviserTypesNothingWhenTheHiveIsAway(t *testing.T) { + srv := httptest.NewServer(nil) + url := srv.URL + srv.Close() // nothing listens at url any more + client, err := callback.NewClient(url, "t") + if err != nil { + t.Fatal(err) + } + client.SetTimeout(200 * time.Millisecond) + sidecar := hivecap.NewKnowledgeAdviser(client, func() bool { return true }, 200*time.Millisecond) + + m, a, typed := advisorManager(t, sidecar) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + baseline, entered := goldenScrollback() + // An unreachable hive never gives a policy, so the advisor stays off: no + // pane is parsed and nothing is typed. + m.adviseKnowledge(a, baseline, workingPane) + for i := 0; i < 3; i++ { + m.adviseKnowledge(a, entered, workingPane) + } + if len(*typed) != 0 { + t.Fatalf("typed with the hive away: %v", *typed) + } + if p := sidecar.Policy(a.Name); p.Enabled { + t.Fatalf("policy with the hive away = %+v", p) + } +} diff --git a/src/crux/api/callback/callback.go b/src/crux/api/callback/callback.go index 2402733ede..ae886246d6 100644 --- a/src/crux/api/callback/callback.go +++ b/src/crux/api/callback/callback.go @@ -36,6 +36,7 @@ // POST /v1/effects/{id}/end report how it ended // POST /v1/tokens/mint issue an agent's short-lived mint credential (stage 4) // GET /v1/bob/credential the Bob API key and where it came from (stage 4) +// POST /v1/knowledge/advise mid-task knowledge advice for a scope an agent entered (hivecommons/hive#17157) package callback import ( @@ -70,6 +71,8 @@ const ( PathEffects = "/" + Version + "/effects" PathAgentMint = "/" + Version + "/tokens/mint" PathBobCredential = "/" + Version + "/bob/credential" + // PathKnowledgeAdvise is the mid-task knowledge adviser route. + PathKnowledgeAdvise = "/" + Version + "/knowledge/advise" ) // InferenceRoutePath is the route for one agent's inference route. @@ -132,6 +135,15 @@ const ( // CodeEffectUnknown is an end for an id hive is not holding: it was // never begun, or already ended, or hive restarted in between. CodeEffectUnknown = "effect_unknown" + // CodeForbidden is a request hive understood and refused on identity + // grounds: POST /v1/knowledge/advise for an agent this runtime does not + // own, or for a kick the agent is no longer in. + CodeForbidden = "forbidden" + // CodeRateLimited is a request hive refused because the runtime is + // asking more often than the contract allows (POST /v1/knowledge/advise: + // a second call in flight for one agent, or a third evaluation of one + // scope in one kick). + CodeRateLimited = "rate_limited" ) // ConditionClassUnavailable is the runtime condition class reserved for @@ -158,6 +170,16 @@ var ( ErrEffectDenied = errors.New("hive mutation boundary denied the effect") // ErrEffectUnknown wraps a 404 CodeEffectUnknown. ErrEffectUnknown = errors.New("hive is not holding that effect") + // ErrForbidden wraps a 403 CodeForbidden. A capability returns it for an + // identity mismatch; the server answers 403 for it. + ErrForbidden = errors.New("hive refused the request for this agent or kick") + // ErrRateLimited wraps a 429 CodeRateLimited. A capability returns it to + // refuse an over-frequent call; the server answers 429 for it. + ErrRateLimited = errors.New("hive refused the request: too many calls") + // ErrInvalidRequest is returned by a capability for a request body that + // parsed but breaks the contract (an over-long pane tail, an unknown + // scope kind); the server answers 400 for it. + ErrInvalidRequest = errors.New("invalid request") ) // DefaultSocket is the socket path hive and the runtime agree on when @@ -213,6 +235,10 @@ const ( // CapabilityBob covers GET /v1/bob/credential; served only by a // Capabilities that also implements BobCredentials. CapabilityBob = "bob" + // CapabilityKnowledgeAdvise covers POST /v1/knowledge/advise; served only + // by a Capabilities that also implements KnowledgeAdvisers, and only + // while the hive's knowledge.sidecar_advise is on (default off). + CapabilityKnowledgeAdvise = "knowledge_advise" ) // MintTokenRequest is the body of POST /v1/tokens. Tier is the permission @@ -481,6 +507,11 @@ type Policy struct { // as JSON. It stays raw so this package keeps importing only the // standard library and crux/api. Sandbox json.RawMessage `json:"sandbox,omitempty"` + // KnowledgeAdvise says hive serves POST /v1/knowledge/advise + // (knowledge.sidecar_advise on, default off). Absent means the runtime + // installs no knowledge adviser and behaves as it did before the route + // existed (hivecommons/hive#17157). + KnowledgeAdvise bool `json:"knowledge_advise,omitempty"` } // BuildInfo is the hive version and commit recorded in kick log headers. @@ -626,3 +657,71 @@ func (c BobCredential) GoString() string { return c.String() } type BobCredentials interface { BobCredential(ctx context.Context) (BobCredential, error) } + +// KnowledgeScope is crux.KnowledgeScope on the wire: one unit of work +// context the runtime observed an agent enter. PaneTail is the last +// pane_lines lines of the agent's scrollback with tokens redacted, present +// only when the policy asked for it. +type KnowledgeScope struct { + Kind string `json:"kind"` + Key string `json:"key"` + Path string `json:"path,omitempty"` + Keywords []string `json:"keywords,omitempty"` + Action string `json:"action,omitempty"` + PaneTail string `json:"pane_tail,omitempty"` +} + +// KnowledgeAdvice is crux.KnowledgeAdvice on the wire: one knowledge entry +// the adviser matched, rendered by the runtime as a single typed line. It is +// data: the runtime types these four fields and nothing else, never a +// ranking model's reason. +type KnowledgeAdvice struct { + Slug string `json:"slug"` + Title string `json:"title"` + Summary string `json:"summary,omitempty"` + Ref string `json:"ref,omitempty"` +} + +// KnowledgeAdvisorPolicy is crux.KnowledgeAdvisorPolicy on the wire: how the +// hive wants advice for one agent delivered. Enabled false means the runtime +// neither parses the agent's pane nor types anything. CooldownMS is the +// minimum gap between two deliveries, in milliseconds; zero or negative means +// the runtime's default. +type KnowledgeAdvisorPolicy struct { + Enabled bool `json:"enabled"` + MaxPerKick int `json:"max_per_kick,omitempty"` + CooldownMS int `json:"cooldown_ms,omitempty"` + WantsPaneTail bool `json:"wants_pane_tail,omitempty"` + PaneLines int `json:"pane_lines,omitempty"` +} + +// KnowledgeAdviseRequest is the body of POST /v1/knowledge/advise. Agent is +// the runtime's agent name and KickAt its current kick identity (the agent's +// LastKick); hive refuses with 403 an agent the runtime does not own or a +// KickAt that is not that agent's current kick. PolicyOnly asks for the +// agent's policy without an evaluation: Scope and KickAt are ignored and no +// candidates are searched, no model is called. Candidates always come from +// the hive's knowledge store under its knowledge.agent_scopes restriction; +// nothing in the request widens that or picks an entry. +type KnowledgeAdviseRequest struct { + Agent string `json:"agent"` + KickAt time.Time `json:"kick_at,omitzero"` + PolicyOnly bool `json:"policy_only,omitempty"` + Scope KnowledgeScope `json:"scope"` +} + +// KnowledgeAdviseResponse is the body of a successful POST +// /v1/knowledge/advise: the advice, best first (empty when nothing applies), +// and the policy in force for the agent. +type KnowledgeAdviseResponse struct { + Advice []KnowledgeAdvice `json:"advice"` + Policy KnowledgeAdvisorPolicy `json:"policy"` +} + +// KnowledgeAdvisers is the mid-task knowledge adviser half of the contract, +// optional like PolicySource: the server answers POST /v1/knowledge/advise +// only when its Caps implements it and reports the capability configured; +// *Client always does. It fails closed: an error means no advice. +type KnowledgeAdvisers interface { + AdviseKnowledge(ctx context.Context, req KnowledgeAdviseRequest) (KnowledgeAdviseResponse, error) +} diff --git a/src/crux/api/callback/callback_test.go b/src/crux/api/callback/callback_test.go index 37ff184e52..2d2a9e2053 100644 --- a/src/crux/api/callback/callback_test.go +++ b/src/crux/api/callback/callback_test.go @@ -53,6 +53,10 @@ type fakeCaps struct { deny bool mints []AgentMintRequest bob BobCredential + advise []KnowledgeAdviseRequest + // adviseResp and adviseErr answer AdviseKnowledge. + adviseResp KnowledgeAdviseResponse + adviseErr error } func (f *fakeCaps) Configured(c string) bool { return !f.absent[c] } @@ -158,6 +162,16 @@ func (f *fakeCaps) BobCredential(context.Context) (BobCredential, error) { return f.bob, f.fail } +func (f *fakeCaps) AdviseKnowledge(_ context.Context, req KnowledgeAdviseRequest) (KnowledgeAdviseResponse, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.advise = append(f.advise, req) + if f.adviseErr != nil { + return KnowledgeAdviseResponse{}, f.adviseErr + } + return f.adviseResp, f.fail +} + func (f *fakeCaps) RepoAutoMergeEnabled(_ context.Context, repo string) (bool, error) { f.mu.Lock() defer f.mu.Unlock() @@ -212,10 +226,11 @@ func (f *fakeCaps) EndEffect(_ context.Context, id string, req EndEffectRequest) } var ( - _ Capabilities = (*fakeCaps)(nil) - _ PolicySource = (*fakeCaps)(nil) - _ InferenceRouter = (*fakeCaps)(nil) - _ EffectBoundary = (*fakeCaps)(nil) + _ Capabilities = (*fakeCaps)(nil) + _ PolicySource = (*fakeCaps)(nil) + _ InferenceRouter = (*fakeCaps)(nil) + _ EffectBoundary = (*fakeCaps)(nil) + _ KnowledgeAdvisers = (*fakeCaps)(nil) ) // shortSocketDir returns a private directory whose socket paths fit in @@ -887,17 +902,19 @@ func TestNotConfiguredSentinelStringAndCodes(t *testing.T) { } // bareCaps has no Configured method: the server assumes every capability -// except the optional-interface ones (policy, inference routes, effects). +// except the optional-interface ones (policy, inference routes, effects, the +// agent mint, Bob) and the knowledge adviser, which is off unless Configured +// says it is on. type bareCaps struct{ Capabilities } func TestCapabilitiesWithoutConfiguredHaveAll(t *testing.T) { c, _ := serveUnix(t, NewServer(bareCaps{&fakeCaps{}}, ""), "") h, err := c.Health(context.Background()) - if err != nil || len(h.Capabilities) != len(allCapabilities)-5 { + if err != nil || len(h.Capabilities) != len(allCapabilities)-6 { t.Errorf("health = %+v, %v", h, err) } for _, name := range h.Capabilities { - if name == CapabilityPolicy || name == CapabilityInferenceRoutes || name == CapabilityEffects { + if name == CapabilityPolicy || name == CapabilityInferenceRoutes || name == CapabilityEffects || name == CapabilityKnowledgeAdvise { t.Errorf("health lists %s for a Capabilities without the optional interface", name) } } @@ -1105,3 +1122,185 @@ func TestAgentMintAndBobOverTheWire(t *testing.T) { t.Fatalf("failing mint = %v", err) } } + +// adviseOnly is a Capabilities that implements KnowledgeAdvisers but, with no +// Configured method, cannot say the route is on. +type adviseOnly struct { + Capabilities + KnowledgeAdvisers +} + +func TestKnowledgeAdviseOverTheWire(t *testing.T) { + kickAt := time.Date(2026, 11, 18, 12, 0, 0, 123456789, time.UTC) + caps := &fakeCaps{adviseResp: KnowledgeAdviseResponse{ + Advice: []KnowledgeAdvice{{Slug: "s1", Title: "T", Summary: "body", Ref: "knowledge entry s1"}}, + Policy: KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, CooldownMS: 1500, WantsPaneTail: true, PaneLines: 40}, + }} + c, logs := serveUnix(t, NewServer(caps, ""), "") + ctx := context.Background() + + req := KnowledgeAdviseRequest{ + Agent: "developer", KickAt: kickAt, + Scope: KnowledgeScope{Kind: "path", Key: "src/crux/agent", Path: "src/crux/agent/a.go", Keywords: []string{"crux"}, Action: "edit", PaneTail: "tail line"}, + } + got, err := c.AdviseKnowledge(ctx, req) + if err != nil { + t.Fatal(err) + } + if len(got.Advice) != 1 || got.Advice[0] != caps.adviseResp.Advice[0] || got.Policy != caps.adviseResp.Policy { + t.Fatalf("response = %+v", got) + } + if len(caps.advise) != 1 || !caps.advise[0].KickAt.Equal(kickAt) || caps.advise[0].Agent != "developer" || caps.advise[0].Scope.PaneTail != "tail line" || + caps.advise[0].Scope.Key != "src/crux/agent" || caps.advise[0].Scope.Action != "edit" || caps.advise[0].PolicyOnly { + t.Fatalf("server saw %+v", caps.advise) + } + if strings.Contains(logs.String(), "tail line") { + t.Fatalf("a request body was logged:\n%s", logs.String()) + } + + // No advice is an empty list on the wire, never null. + caps.adviseResp = KnowledgeAdviseResponse{} + empty, err := c.AdviseKnowledge(ctx, req) + if err != nil || empty.Advice == nil || len(empty.Advice) != 0 { + t.Fatalf("empty response = %+v, %v", empty, err) + } + + // A policy request carries no scope. + if _, err := c.AdviseKnowledge(ctx, KnowledgeAdviseRequest{Agent: "developer", PolicyOnly: true}); err != nil { + t.Fatal(err) + } + if last := caps.advise[len(caps.advise)-1]; !last.PolicyOnly || !last.KickAt.IsZero() { + t.Fatalf("policy request as seen = %+v", last) + } + + var se *api.StatusError + if _, err := c.AdviseKnowledge(ctx, KnowledgeAdviseRequest{}); !errors.As(err, &se) || se.Status != http.StatusBadRequest { + t.Fatalf("no agent = %v, want 400", err) + } + + // Capability errors map to their statuses, and the client maps them back. + for _, tt := range []struct { + name string + err error + status int + is error + }{ + {"forbidden", fmt.Errorf("%w: not yours", ErrForbidden), http.StatusForbidden, ErrForbidden}, + {"rate limited", fmt.Errorf("%w: slow down", ErrRateLimited), http.StatusTooManyRequests, ErrRateLimited}, + {"invalid", fmt.Errorf("%w: too long", ErrInvalidRequest), http.StatusBadRequest, nil}, + {"not configured", ErrNotConfigured, http.StatusNotFound, ErrNotConfigured}, + {"upstream", errors.New("store down"), http.StatusBadGateway, ErrUnavailable}, + } { + caps.adviseErr = tt.err + _, err := c.AdviseKnowledge(ctx, req) + if err == nil { + t.Errorf("%s: no error", tt.name) + continue + } + if tt.is != nil && !errors.Is(err, tt.is) { + t.Errorf("%s: err = %v, want %v", tt.name, err, tt.is) + } + if tt.is == nil && (!errors.As(err, &se) || se.Status != tt.status) { + t.Errorf("%s: err = %v, want status %d", tt.name, err, tt.status) + } + } +} + +// The route is served only for a Capabilities that says it is configured: a +// bare one is not served even when it implements the interface, and one that +// denies it answers 404 not_configured and stays out of Health. +func TestKnowledgeAdviseIsOffUnlessConfigured(t *testing.T) { + ctx := context.Background() + req := KnowledgeAdviseRequest{Agent: "developer", PolicyOnly: true} + + for name, caps := range map[string]Capabilities{ + "bare": adviseOnly{Capabilities: &fakeCaps{}, KnowledgeAdvisers: &fakeCaps{}}, + "absent": &fakeCaps{absent: map[string]bool{CapabilityKnowledgeAdvise: true}}, + } { + c, _ := serveUnix(t, NewServer(caps, ""), "") + h, err := c.Health(ctx) + if err != nil { + t.Fatal(err) + } + for _, listed := range h.Capabilities { + if listed == CapabilityKnowledgeAdvise { + t.Errorf("%s: health lists the knowledge adviser", name) + } + } + if _, err := c.AdviseKnowledge(ctx, req); !errors.Is(err, ErrNotConfigured) { + t.Errorf("%s: err = %v, want not_configured", name, err) + } + } + if !(&fakeCaps{}).Configured(CapabilityKnowledgeAdvise) { + t.Fatal("fakeCaps must report the capability configured by default") + } + // A Capabilities with no KnowledgeAdvisers at all (every existing one) is + // not served either. + c, _ := serveUnix(t, NewServer(bareCaps{&fakeCaps{}}, ""), "") + if _, err := c.AdviseKnowledge(ctx, req); !errors.Is(err, ErrNotConfigured) { + t.Errorf("no interface: err = %v, want not_configured", err) + } +} + +// A body past the byte cap is refused with 413 before it reaches the +// capability, and the route sits behind the same bearer check as the rest. +func TestKnowledgeAdviseBodyCapAndAuth(t *testing.T) { + caps := &fakeCaps{} + ts := httptest.NewServer(NewServer(caps, testBearer).Handler()) + t.Cleanup(ts.Close) + post := func(auth, body string) int { + req, err := http.NewRequest(http.MethodPost, ts.URL+PathKnowledgeAdvise, strings.NewReader(body)) + if err != nil { + t.Fatal(err) + } + if auth != "" { + req.Header.Set("Authorization", auth) + } + resp, err := ts.Client().Do(req) + if err != nil { + t.Fatal(err) + } + _ = resp.Body.Close() + return resp.StatusCode + } + big := `{"agent":"a","scope":{"kind":"path","key":"k","pane_tail":"` + strings.Repeat("x", maxKnowledgeAdviseBodyBytes) + `"}}` + if got := post("Bearer "+testBearer, big); got != http.StatusRequestEntityTooLarge { + t.Errorf("oversize body: status %d, want 413", got) + } + if got := post("Bearer "+testBearer, `{"agent":`); got != http.StatusBadRequest { + t.Errorf("malformed body: status %d, want 400", got) + } + if got := post("", `{"agent":"a"}`); got != http.StatusUnauthorized { + t.Errorf("no token: status %d, want 401", got) + } + if got := post("Bearer nope", `{"agent":"a"}`); got != http.StatusUnauthorized { + t.Errorf("wrong token: status %d, want 401", got) + } + if len(caps.advise) != 0 { + t.Fatalf("refused requests reached the capability: %+v", caps.advise) + } + if got := post("Bearer "+testBearer, `{"agent":"a","policy_only":true}`); got != http.StatusOK { + t.Errorf("valid request: status %d, want 200", got) + } +} + +// The wire names are the contract the runtime and hive agree on. +func TestKnowledgeAdviseWireNames(t *testing.T) { + if PathKnowledgeAdvise != "/v1/knowledge/advise" || CapabilityKnowledgeAdvise != "knowledge_advise" { + t.Fatalf("route %q, capability %q", PathKnowledgeAdvise, CapabilityKnowledgeAdvise) + } + b, err := json.Marshal(KnowledgeAdviseRequest{Agent: "a", PolicyOnly: true}) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(b), "kick_at") { + t.Errorf("a zero kick is omitted from the body: %s", b) + } + p, err := json.Marshal(Policy{}) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(p), "knowledge_advise") { + t.Errorf("an unset knowledge_advise changes the policy snapshot: %s", p) + } +} diff --git a/src/crux/api/callback/client.go b/src/crux/api/callback/client.go index 2bee134fb3..1a0d126825 100644 --- a/src/crux/api/callback/client.go +++ b/src/crux/api/callback/client.go @@ -210,10 +210,11 @@ func (c *Client) EndEffect(ctx context.Context, id string, req EndEffectRequest) } var ( - _ Capabilities = (*Client)(nil) - _ PolicySource = (*Client)(nil) - _ InferenceRouter = (*Client)(nil) - _ EffectBoundary = (*Client)(nil) + _ Capabilities = (*Client)(nil) + _ PolicySource = (*Client)(nil) + _ InferenceRouter = (*Client)(nil) + _ EffectBoundary = (*Client)(nil) + _ KnowledgeAdvisers = (*Client)(nil) ) // do performs one call. Transport failures, timeouts and 5xx become @@ -293,6 +294,10 @@ func (c *Client) checkStatus(resp *http.Response, method, path string) error { return fmt.Errorf("%w: %s", ErrEffectDenied, se.Body.Error) case resp.StatusCode == http.StatusNotFound && se.Body.Code == CodeEffectUnknown: return fmt.Errorf("%w: %s %s", ErrEffectUnknown, method, path) + case resp.StatusCode == http.StatusForbidden && se.Body.Code == CodeForbidden: + return fmt.Errorf("%w: %s %s", ErrForbidden, method, path) + case resp.StatusCode == http.StatusTooManyRequests && se.Body.Code == CodeRateLimited: + return fmt.Errorf("%w: %s %s", ErrRateLimited, method, path) case resp.StatusCode >= 500: return fmt.Errorf("%w: %s %s: HTTP %d %s: %w", ErrUnavailable, method, path, resp.StatusCode, se.Body.Code, se) } @@ -335,3 +340,11 @@ func (c *Client) BobCredential(ctx context.Context) (BobCredential, error) { err := c.do(ctx, http.MethodGet, PathBobCredential, nil, &out) return out, err } + +// AdviseKnowledge is POST /v1/knowledge/advise. A hive that has not turned +// the route on answers 404 not_configured (ErrNotConfigured). +func (c *Client) AdviseKnowledge(ctx context.Context, req KnowledgeAdviseRequest) (KnowledgeAdviseResponse, error) { + var out KnowledgeAdviseResponse + err := c.do(ctx, http.MethodPost, PathKnowledgeAdvise, req, &out) + return out, err +} diff --git a/src/crux/api/callback/server.go b/src/crux/api/callback/server.go index 3f526951c5..e52149ca0a 100644 --- a/src/crux/api/callback/server.go +++ b/src/crux/api/callback/server.go @@ -24,6 +24,11 @@ const ( // maxBodyBytes bounds a request body. Scan bodies are the largest; the // proxy already caps the GitHub write bodies it scans well under this. maxBodyBytes = 4 << 20 + // maxKnowledgeAdviseBodyBytes bounds a POST /v1/knowledge/advise body. + // The largest legitimate one is a scope plus a pane tail of the + // configured pane_lines lines; 64 KiB is several times that, and a body + // past it is refused without being read (hivecommons/hive#17157). + maxKnowledgeAdviseBodyBytes = 64 << 10 // shutdownGrace is how long Serve waits for in-flight requests. shutdownGrace = 5 * time.Second // networkUnix tags requests that arrived on the unix socket. @@ -96,6 +101,7 @@ func (s *Server) Handler() http.Handler { mux.HandleFunc("POST "+PathEffects+"/{id}/end", s.capability(CapabilityEffects, s.handleEndEffect)) mux.HandleFunc("POST "+PathAgentMint, s.capability(CapabilityAgentMint, s.handleAgentMint)) mux.HandleFunc("GET "+PathBobCredential, s.capability(CapabilityBob, s.handleBobCredential)) + mux.HandleFunc("POST "+PathKnowledgeAdvise, s.capability(CapabilityKnowledgeAdvise, s.handleKnowledgeAdvise)) return s.instrument(s.authenticate(mux)) } @@ -148,6 +154,14 @@ func (s *Server) configured(capability string) bool { if _, ok := s.Caps.(BobCredentials); !ok { return false } + case CapabilityKnowledgeAdvise: + if _, ok := s.Caps.(KnowledgeAdvisers); !ok { + return false + } + // Unlike the other optional capabilities this one is off by default, + // so a Capabilities without a Configured answer must not serve it. + c, ok := s.Caps.(Configured) + return ok && c.Configured(capability) } if c, ok := s.Caps.(Configured); ok { return c.Configured(capability) @@ -173,7 +187,7 @@ var allCapabilities = []string{ CapabilityTokens, CapabilityGitHubREST, CapabilityUsage, CapabilityCanary, CapabilityText, CapabilityConditions, CapabilityLinear, CapabilityPulls, CapabilityPolicy, CapabilityInferenceRoutes, CapabilityEffects, - CapabilityAgentMint, CapabilityBob, + CapabilityAgentMint, CapabilityBob, CapabilityKnowledgeAdvise, } func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) { @@ -429,13 +443,24 @@ func (s *Server) handleEndEffect(w http.ResponseWriter, r *http.Request) { } // writeCapabilityError maps a Capabilities error: ErrNotConfigured → 404, +// ErrInvalidRequest → 400, ErrForbidden → 403, ErrRateLimited → 429, // anything else → 502 CodeUpstream with the message. The message is the // implementation's; hive-side code is responsible for keeping secrets out // of the errors it returns, as it already is for its logs. func (s *Server) writeCapabilityError(w http.ResponseWriter, r *http.Request, verb string, err error) { - if errors.Is(err, ErrNotConfigured) { + switch { + case errors.Is(err, ErrNotConfigured): s.writeError(w, r, http.StatusNotFound, CodeNotConfigured, verb+": "+err.Error()) return + case errors.Is(err, ErrInvalidRequest): + s.writeError(w, r, http.StatusBadRequest, CodeBadRequest, verb+": "+err.Error()) + return + case errors.Is(err, ErrForbidden): + s.writeError(w, r, http.StatusForbidden, CodeForbidden, verb+": "+err.Error()) + return + case errors.Is(err, ErrRateLimited): + s.writeError(w, r, http.StatusTooManyRequests, CodeRateLimited, verb+": "+err.Error()) + return } s.writeError(w, r, http.StatusBadGateway, CodeUpstream, verb+": "+err.Error()) } @@ -664,3 +689,35 @@ func (s *Server) handleBobCredential(w http.ResponseWriter, r *http.Request) { } s.writeJSON(w, r, http.StatusOK, cred) } + +// handleKnowledgeAdvise answers a runtime's mid-task knowledge request. The +// body is read through a hard byte cap (413 past it, nothing buffered beyond +// it); the identity, scope and pane-length checks, the per-agent and per-kick +// rate limits and the evaluation itself are the Capabilities'. Every refusal +// is a non-2xx, which the runtime reads as "no advice". +func (s *Server) handleKnowledgeAdvise(w http.ResponseWriter, r *http.Request) { + var req KnowledgeAdviseRequest + body := http.MaxBytesReader(w, r.Body, maxKnowledgeAdviseBodyBytes) + if err := json.NewDecoder(body).Decode(&req); err != nil { + var tooLarge *http.MaxBytesError + if errors.As(err, &tooLarge) { + s.writeError(w, r, http.StatusRequestEntityTooLarge, CodeBadRequest, "request body is too large") + return + } + s.writeError(w, r, http.StatusBadRequest, CodeBadRequest, "invalid JSON body") + return + } + if req.Agent == "" { + s.writeError(w, r, http.StatusBadRequest, CodeBadRequest, "agent is required") + return + } + resp, err := s.Caps.(KnowledgeAdvisers).AdviseKnowledge(r.Context(), req) + if err != nil { + s.writeCapabilityError(w, r, "advising knowledge", err) + return + } + if resp.Advice == nil { + resp.Advice = []KnowledgeAdvice{} + } + s.writeJSON(w, r, http.StatusOK, resp) +} diff --git a/src/crux/api/client/client_test.go b/src/crux/api/client/client_test.go index 8675983219..503fc73dea 100644 --- a/src/crux/api/client/client_test.go +++ b/src/crux/api/client/client_test.go @@ -102,7 +102,7 @@ func TestParityHostVersusSetterTable(t *testing.T) { callback.PathTokens: true, callback.PathPolicy: true, callback.PathRepoAutoMerge: true, callback.PathLinearCredential: true, callback.PathPulls: true, callback.PathConditions: true, callback.PathInferenceRoutes + "/{agent}": true, callback.PathEffects: true, callback.PathEffects + "/{id}/end": true, - callback.PathAgentMint: true, callback.PathBobCredential: true, + callback.PathAgentMint: true, callback.PathBobCredential: true, callback.PathKnowledgeAdvise: true, } events := map[string]bool{api.EventKickOutcome: true, api.EventPauseTransition: true, api.EventRelaunch: true, api.EventPausePersist: true, api.EventPrompt: true, api.EventSandboxAudit: true, api.EventAudit: true, api.EventCondition: true} for name, row := range api.HostSetters { @@ -139,11 +139,14 @@ func TestParityHostVersusSetterTable(t *testing.T) { t.Errorf("api.HostSetters[%q] has unknown kind %q", name, row.Kind) } } - for _, name := range []string{"SetSpanStarter", "SetKnowledgeAdviser", "SetSandboxGitHubReadRelay"} { + for _, name := range []string{"SetSpanStarter", "SetSandboxGitHubReadRelay"} { if api.HostSetters[name].Kind != api.HostSetterInProcessOnly { t.Errorf("%s is an in-process-only setter", name) } } + if row := api.HostSetters["SetKnowledgeAdviser"]; row.Kind != api.HostSetterCallback || !strings.Contains(row.Via, callback.PathKnowledgeAdvise) { + t.Errorf("SetKnowledgeAdviser is served by the knowledge advise callback route, got %+v", row) + } } type harness struct { diff --git a/src/crux/api/runtime.go b/src/crux/api/runtime.go index a38c795725..8b8204fdae 100644 --- a/src/crux/api/runtime.go +++ b/src/crux/api/runtime.go @@ -779,6 +779,7 @@ const ( hostViaInferenceRoutes = "PUT|DELETE /v1/inference/routes/{agent}" hostViaEffects = "POST /v1/effects, POST /v1/effects/{id}/end" hostViaConditions = "POST /v1/conditions" + hostViaKnowledgeAdvise = "POST /v1/knowledge/advise" ) // HostSetters maps every crux.Host setter to how a sidecar runtime gets @@ -808,6 +809,10 @@ var HostSetters = map[string]HostSetter{ // Calls into hive -> their own callback families (stage 4). "SetInferenceCallbacks": {HostSetterCallback, hostViaInferenceRoutes}, "SetSandboxMutationBoundary": {HostSetterCallback, hostViaEffects}, + // The mid-task knowledge adviser: the hive's policy snapshot says whether + // the route is on (knowledge.sidecar_advise, default off), and the route + // carries each scope and its advice (hivecommons/hive#17157). + "SetKnowledgeAdviser": {HostSetterCallback, hostViaPolicy + ", " + hostViaKnowledgeAdvise}, // Observers -> the event stream (stage 3). Conditions also go back // over the callback so hive's fleet report sees them. @@ -822,5 +827,4 @@ var HostSetters = map[string]HostSetter{ // In-process only. "SetSpanStarter": {HostSetterInProcessOnly, "OpenTelemetry global tracer in the runtime process; trajectory events are independent of spans"}, "SetSandboxGitHubReadRelay": {HostSetterInProcessOnly, "the relay holds the read-only GitHub credential and Enroll is a Go call into hive's proxy; neither crosses into a runtime process, so a sidecar runtime's Job kicks read GitHub without the relay (hivecommons/hive#18865)"}, - "SetKnowledgeAdviser": {HostSetterInProcessOnly, "the knowledge store lives in the hive process; a sidecar runtime runs without the mid-task knowledge advisor (hivecommons/hive#17052 phase 1)"}, } diff --git a/src/crux/cli/hive_callback.go b/src/crux/cli/hive_callback.go index f98cef8013..1ea13dff93 100644 --- a/src/crux/cli/hive_callback.go +++ b/src/crux/cli/hive_callback.go @@ -50,6 +50,13 @@ type hivePolicyTarget interface { SetDeadSessionRecoveryOwner(ownedElsewhere bool) } +// hiveKnowledgeTarget is the manager's mid-task knowledge adviser setter. It +// is separate from hivePolicyTarget so a runtime without the advisor still +// takes the policy snapshot. +type hiveKnowledgeTarget interface { + SetKnowledgeAdviser(crux.KnowledgeAdviser) +} + // policyApplier turns each new policy snapshot into setter calls. Resolvers // are installed once, the first time hive reports the value, and then read // the live snapshot; the pushed values (sandbox config, dead-session owner) @@ -60,6 +67,13 @@ type policyApplier struct { policy *hivecap.Policy errw io.Writer + // knowledge and adviser, when set, install the sidecar knowledge adviser + // the first time a snapshot says the hive serves POST + // /v1/knowledge/advise (knowledge.sidecar_advise, default off). A hive + // that never says so leaves the runtime exactly as it was. + knowledge hiveKnowledgeTarget + adviser crux.KnowledgeAdviser + mu sync.Mutex installed map[string]bool sandbox []byte @@ -85,6 +99,7 @@ func (a *policyApplier) apply(pol callback.Policy) { once("kick_log_source", pol.KickLogSource != nil, func() { a.target.SetKickLogSourceResolver(p.KickLogSource) }) once("gateway_backends", pol.GatewayBackends != nil, func() { a.target.SetGatewayBackendChecker(p.GatewayBackend) }) once("repo_auto_merge", pol.RepoAutoMerge, func() { a.target.SetRepoAutoMergeEnabledResolver(p.RepoAutoMergeEnabled) }) + once("knowledge_advise", pol.KnowledgeAdvise && a.knowledge != nil && a.adviser != nil, func() { a.knowledge.SetKnowledgeAdviser(a.adviser) }) if v := pol.DeadSessionRecoveryOwnedElsewhere; v != nil && (a.owner == nil || *a.owner != *v) { owned := *v a.owner = &owned @@ -171,7 +186,11 @@ func (h *hiveCallback) watchPolicy(ctx context.Context, rt crux.Runtime, w, errw if !ok { return } - go hivecap.WatchPolicy(ctx, h.set.Policy, 0, newPolicyApplier(m, h.set.Policy, errw).apply) + applier := newPolicyApplier(m, h.set.Policy, errw) + if kt, ok := rt.(hiveKnowledgeTarget); ok { + applier.knowledge, applier.adviser = kt, h.set.Knowledge + } + go hivecap.WatchPolicy(ctx, h.set.Policy, 0, applier.apply) fmt.Fprintf(w, "hive callback %s: host policy\n", addressString(h.client.Address())) } diff --git a/src/crux/cli/hive_policy_test.go b/src/crux/cli/hive_policy_test.go index b4e51507c1..0bd5656662 100644 --- a/src/crux/cli/hive_policy_test.go +++ b/src/crux/cli/hive_policy_test.go @@ -9,6 +9,7 @@ import ( "testing" "time" + "github.com/hivecommons/hive/crux" "github.com/hivecommons/hive/crux/api/callback" "github.com/hivecommons/hive/crux/config" "github.com/hivecommons/hive/crux/hivecap" @@ -206,3 +207,73 @@ func TestWatchPolicyOverTheCallback(t *testing.T) { t.Fatalf("explain = %q", got) } } + +// knowledgePolicyTarget is a policyTarget whose manager also takes the +// mid-task knowledge adviser. +type knowledgePolicyTarget struct { + *policyTarget + advisers []crux.KnowledgeAdviser +} + +func (k *knowledgePolicyTarget) SetKnowledgeAdviser(a crux.KnowledgeAdviser) { + k.mu.Lock() + defer k.mu.Unlock() + k.advisers = append(k.advisers, a) +} + +// The sidecar knowledge adviser is installed the first time a snapshot says +// the hive serves the route, once, and never when it does not: a hive without +// knowledge.sidecar_advise leaves the runtime exactly as it was. +func TestPolicyApplierInstallsTheKnowledgeAdviserOnlyWhenTheHiveServesTheRoute(t *testing.T) { + hive := &policyHive{} + pol := hivecap.NewPolicy(hive, time.Second) + target := &knowledgePolicyTarget{policyTarget: &policyTarget{fakeRuntime: &fakeRuntime{}}} + var errw strings.Builder + a := newPolicyApplier(target, pol, &errw) + a.knowledge, a.adviser = target, hivecap.NewKnowledgeAdviser(hive, pol.KnowledgeAdvise, 0) + + a.apply(callback.Policy{}) + a.apply(callback.Policy{RepoAutoMerge: true}) + if len(target.advisers) != 0 { + t.Fatalf("adviser installed from snapshots that do not advertise the route: %d", len(target.advisers)) + } + + a.apply(callback.Policy{KnowledgeAdvise: true}) + a.apply(callback.Policy{KnowledgeAdvise: true, RepoAutoMerge: true}) + a.apply(callback.Policy{}) + a.apply(callback.Policy{KnowledgeAdvise: true}) + if len(target.advisers) != 1 || target.advisers[0] != a.adviser { + t.Fatalf("adviser installs = %d, want exactly one (the applier's)", len(target.advisers)) + } + + // A target that cannot take an adviser, or an applier with none, installs + // nothing and does not fail. + plain := newPolicyApplier(&policyTarget{fakeRuntime: &fakeRuntime{}}, pol, &errw) + plain.apply(callback.Policy{KnowledgeAdvise: true}) +} + +// watchPolicy wires the manager's adviser setter into the applier. +func TestWatchPolicyInstallsTheKnowledgeAdviserFromTheCallback(t *testing.T) { + hive := &policyHive{policy: callback.Policy{KnowledgeAdvise: true}} + sock := filepath.Join(shortSocketDir(t), "hive.sock") + ls, err := callback.Listen(callback.ListenConfig{Socket: sock}) + if err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + go func() { _ = callback.NewServer(hive, "").Serve(ctx, ls) }() + + h, err := dialHiveCallback(sock, "") + if err != nil { + t.Fatal(err) + } + target := &knowledgePolicyTarget{policyTarget: &policyTarget{fakeRuntime: &fakeRuntime{}}} + var out, errw strings.Builder + h.watchPolicy(ctx, target, &out, &errw) + testutil.Eventually(t, 5*time.Second, func() bool { + target.mu.Lock() + defer target.mu.Unlock() + return len(target.advisers) == 1 + }, "the knowledge adviser was never installed from the callback's policy") +} diff --git a/src/crux/hivecap/hivecap.go b/src/crux/hivecap/hivecap.go index c3b7fb0e64..d637f15743 100644 --- a/src/crux/hivecap/hivecap.go +++ b/src/crux/hivecap/hivecap.go @@ -66,6 +66,10 @@ type Set struct { AppTokens *AppTokenWriter Mint AgentMint Bob *BobCredentials + // Knowledge is the sidecar's SetKnowledgeAdviser argument + // (hivecommons/hive#17157). It is inert until the hive's policy snapshot + // says the route is on. + Knowledge *KnowledgeAdviser } // New builds the adapters over caps. timeout bounds the calls made from @@ -87,6 +91,7 @@ func New(caps callback.Capabilities, timeout time.Duration) *Set { s.Mint = NewAgentMint(caps, timeout) s.Bob = NewBobCredentials(caps, timeout) s.Policy = NewPolicy(caps, timeout) + s.Knowledge = NewKnowledgeAdviser(caps, s.Policy.KnowledgeAdvise, 0) s.Inference = NewInferenceRoutes(caps, timeout) s.Mutation = NewMutationBoundary(caps) return s @@ -512,6 +517,14 @@ func (p *Policy) KickLogSource() string { return "" } +// KnowledgeAdvise reports whether the last snapshot says the hive serves POST +// /v1/knowledge/advise. False without a snapshot, so a runtime that has not +// heard from the hive (or talks to one that predates the route) never calls it. +func (p *Policy) KnowledgeAdvise() bool { + pol, _ := p.Snapshot() + return pol.KnowledgeAdvise +} + // GatewayBackend is the SetGatewayBackendChecker predicate: backend names a // gateway hive has configured. The empty backend is the default, never a // named gateway, matching hive's own predicate. diff --git a/src/crux/hivecap/knowledge.go b/src/crux/hivecap/knowledge.go new file mode 100644 index 0000000000..f406551a65 --- /dev/null +++ b/src/crux/hivecap/knowledge.go @@ -0,0 +1,253 @@ +package hivecap + +import ( + "context" + "log/slog" + "sync" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/api/callback" + "github.com/hivecommons/hive/crux/logscrub" +) + +// The mid-task knowledge adviser for a sidecar runtime (hivecommons/hive#17157). +// In-process, hive hands the manager a crux.KnowledgeAdviser that searches the +// knowledge store in its own address space (SetKnowledgeAdviser). A sidecar +// runtime has no such store, and must never hold the inference credentials the +// ranking pass spends, so the adviser here sends the observed scope (and the +// redacted pane tail, when the policy asks for it) to POST /v1/knowledge/advise +// and receives advice lines back. Everything that decides what is advised stays +// on the hive. + +const ( + // DefaultKnowledgeAdviseTimeout bounds one advise call. The hive may run + // a model pass behind it (up to its own decision timeout), so this is + // longer than callback.DefaultTimeout; the runtime calls it off the poll + // goroutine, one call per agent at a time. + DefaultKnowledgeAdviseTimeout = 30 * time.Second + // DefaultKnowledgePolicyTTL is how long a per-agent policy answer is + // kept before it is fetched again in the background, so a hive config + // change reaches a running agent within it. + DefaultKnowledgePolicyTTL = 30 * time.Second + // maxKnowledgeAdviceLines caps how many advice entries one response is + // allowed to hand the runtime, whatever the hive sent. + maxKnowledgeAdviceLines = 8 +) + +// KnowledgeAdviser implements crux.KickBoundKnowledgeAdviser over POST +// /v1/knowledge/advise. It fails closed everywhere: while the hive does not +// advertise the route, Policy reports the advisor disabled (so the runtime +// parses no pane and types nothing); any transport error, non-2xx or +// malformed body is no advice, logged once per kick. The runtime, not this +// adapter, types the lines, and it types only the four KnowledgeAdvice fields. +type KnowledgeAdviser struct { + caps callback.KnowledgeAdvisers + enabled func() bool + timeout time.Duration + // TTL is how long a policy answer is kept; non-positive selects + // DefaultKnowledgePolicyTTL. + TTL time.Duration + // Logger receives the one warning per failed kick; nil is slog.Default(). + Logger *slog.Logger + now func() time.Time + // spawn runs a background policy refresh; tests run it inline. + spawn func(func()) + + mu sync.Mutex + policies map[string]*knowledgePolicyState + warned map[string]time.Time +} + +type knowledgePolicyState struct { + policy crux.KnowledgeAdvisorPolicy + fetchedAt time.Time + refreshing bool + failing bool +} + +var _ crux.KickBoundKnowledgeAdviser = (*KnowledgeAdviser)(nil) + +// NewKnowledgeAdviser builds the adviser over caps. enabled reports whether +// the hive currently advertises the route (the policy snapshot's +// KnowledgeAdvise flag); nil or a caps that is not a +// callback.KnowledgeAdvisers makes the adviser permanently disabled. +// Non-positive timeout selects DefaultKnowledgeAdviseTimeout. +func NewKnowledgeAdviser(caps any, enabled func() bool, timeout time.Duration) *KnowledgeAdviser { + if timeout <= 0 { + timeout = DefaultKnowledgeAdviseTimeout + } + k := &KnowledgeAdviser{ + enabled: enabled, + timeout: timeout, + now: time.Now, + spawn: func(f func()) { go f() }, + policies: map[string]*knowledgePolicyState{}, + warned: map[string]time.Time{}, + } + k.caps, _ = caps.(callback.KnowledgeAdvisers) + return k +} + +func (k *KnowledgeAdviser) on() bool { + return k != nil && k.caps != nil && k.enabled != nil && k.enabled() +} + +func (k *KnowledgeAdviser) ttl() time.Duration { + if k.TTL > 0 { + return k.TTL + } + return DefaultKnowledgePolicyTTL +} + +func (k *KnowledgeAdviser) logger() *slog.Logger { + if k.Logger != nil { + return k.Logger + } + return slog.Default() +} + +// Policy answers from the last policy the hive gave for agent and never waits +// on the hive: the manager reads it on every poll tick. The first call for an +// agent, and each call after the TTL, starts a background fetch; until the +// first answer lands (and whenever the last fetch failed, or the hive does not +// advertise the route) the policy is the zero value, so the advisor is off. +func (k *KnowledgeAdviser) Policy(agent string) crux.KnowledgeAdvisorPolicy { + if !k.on() || agent == "" { + return crux.KnowledgeAdvisorPolicy{} + } + k.mu.Lock() + st := k.policies[agent] + if st == nil { + st = &knowledgePolicyState{} + k.policies[agent] = st + } + refresh := !st.refreshing && (st.fetchedAt.IsZero() || k.now().Sub(st.fetchedAt) >= k.ttl()) + if refresh { + st.refreshing = true + } + policy := st.policy + k.mu.Unlock() + if refresh { + k.spawn(func() { k.refreshPolicy(agent) }) + } + return policy +} + +// refreshPolicy asks the hive for agent's policy without an evaluation. +func (k *KnowledgeAdviser) refreshPolicy(agent string) { + ctx, cancel := context.WithTimeout(context.Background(), k.timeout) + defer cancel() + resp, err := k.caps.AdviseKnowledge(ctx, callback.KnowledgeAdviseRequest{Agent: agent, PolicyOnly: true}) + + k.mu.Lock() + st := k.policies[agent] + if st == nil { + st = &knowledgePolicyState{} + k.policies[agent] = st + } + st.refreshing = false + st.fetchedAt = k.now() + wasFailing := st.failing + st.failing = err != nil + if err != nil { + st.policy = crux.KnowledgeAdvisorPolicy{} + } else { + st.policy = cruxPolicy(resp.Policy) + } + k.mu.Unlock() + if err != nil && !wasFailing { + k.logger().Warn("hive knowledge advise policy unavailable; the mid-task advisor stays off for this agent", "agent", agent, "error", err.Error()) + } +} + +// Advise is the plain seam; the runtime uses AdviseForKick, which carries the +// kick identity the hive requires. Without one there is no advice. +func (k *KnowledgeAdviser) Advise(string, crux.KnowledgeScope) []crux.KnowledgeAdvice { return nil } + +// AdviseForKick sends scope to the hive and returns its advice. The pane tail +// is redacted again here, whatever the runtime did to it, so no token from the +// logscrub set is ever in a request body. +func (k *KnowledgeAdviser) AdviseForKick(agent string, kickAt time.Time, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + if !k.on() || agent == "" || kickAt.IsZero() { + return nil + } + ctx, cancel := context.WithTimeout(context.Background(), k.timeout) + defer cancel() + resp, err := k.caps.AdviseKnowledge(ctx, callback.KnowledgeAdviseRequest{ + Agent: agent, + KickAt: kickAt, + Scope: wireScope(scope), + }) + if err != nil { + k.warnOnce(agent, kickAt, err) + return nil + } + k.learnPolicy(agent, resp.Policy) + advice := resp.Advice + if len(advice) > maxKnowledgeAdviceLines { + advice = advice[:maxKnowledgeAdviceLines] + } + out := make([]crux.KnowledgeAdvice, 0, len(advice)) + for _, a := range advice { + if a.Slug == "" { + continue + } + out = append(out, crux.KnowledgeAdvice{Slug: a.Slug, Title: a.Title, Summary: a.Summary, Ref: a.Ref}) + } + return out +} + +// learnPolicy keeps the policy an advise response carried as the agent's +// current one. +func (k *KnowledgeAdviser) learnPolicy(agent string, p callback.KnowledgeAdvisorPolicy) { + k.mu.Lock() + defer k.mu.Unlock() + st := k.policies[agent] + if st == nil { + st = &knowledgePolicyState{} + k.policies[agent] = st + } + st.policy = cruxPolicy(p) + st.fetchedAt = k.now() + st.failing = false +} + +// warnOnce logs the first failure of a kick and swallows the rest: a hive +// that is away costs one line per kick, not one per poll tick. +func (k *KnowledgeAdviser) warnOnce(agent string, kickAt time.Time, err error) { + k.mu.Lock() + seen, ok := k.warned[agent] + k.warned[agent] = kickAt + k.mu.Unlock() + if ok && seen.Equal(kickAt) { + return + } + k.logger().Warn("hive knowledge advise failed; no advice for this kick", "agent", agent, "error", err.Error()) +} + +// wireScope is the scope as it crosses to the hive: every free-text field +// through the same redaction the pane tail gets. +func wireScope(s crux.KnowledgeScope) callback.KnowledgeScope { + out := callback.KnowledgeScope{ + Kind: s.Kind, + Key: logscrub.RedactPaneTokens(s.Key), + Path: logscrub.RedactPaneTokens(s.Path), + Action: s.Action, + PaneTail: logscrub.RedactPaneTokens(s.PaneTail), + } + for _, kw := range s.Keywords { + out.Keywords = append(out.Keywords, logscrub.RedactPaneTokens(kw)) + } + return out +} + +func cruxPolicy(p callback.KnowledgeAdvisorPolicy) crux.KnowledgeAdvisorPolicy { + return crux.KnowledgeAdvisorPolicy{ + Enabled: p.Enabled, + MaxPerKick: p.MaxPerKick, + Cooldown: time.Duration(p.CooldownMS) * time.Millisecond, + WantsPaneTail: p.WantsPaneTail, + PaneLines: p.PaneLines, + } +} diff --git a/src/crux/hivecap/knowledge_test.go b/src/crux/hivecap/knowledge_test.go new file mode 100644 index 0000000000..9ae67ab16c --- /dev/null +++ b/src/crux/hivecap/knowledge_test.go @@ -0,0 +1,402 @@ +package hivecap + +import ( + "bytes" + "context" + "fmt" + "log/slog" + "os" + "path/filepath" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/api/callback" +) + +// The sidecar knowledge adviser (hivecommons/hive#17157): off until the hive +// advertises the route, fail closed everywhere, one warning per kick. + +const testToken = "ghp_abcdefghijklmnopqrstuvwxyz0123456789" + +type fakeAdviseCaps struct { + mu sync.Mutex + reqs []callback.KnowledgeAdviseRequest + resp callback.KnowledgeAdviseResponse + err error +} + +func (f *fakeAdviseCaps) AdviseKnowledge(_ context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.reqs = append(f.reqs, req) + return f.resp, f.err +} + +func (f *fakeAdviseCaps) calls() []callback.KnowledgeAdviseRequest { + f.mu.Lock() + defer f.mu.Unlock() + return append([]callback.KnowledgeAdviseRequest(nil), f.reqs...) +} + +type adviserHarness struct { + k *KnowledgeAdviser + caps *fakeAdviseCaps + on *atomic.Bool + logs *bytes.Buffer + now *time.Time +} + +func newAdviserHarness(t *testing.T) *adviserHarness { + t.Helper() + caps := &fakeAdviseCaps{resp: callback.KnowledgeAdviseResponse{ + Policy: callback.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, CooldownMS: 45000, WantsPaneTail: true, PaneLines: 30}, + }} + on := &atomic.Bool{} + on.Store(true) + h := &adviserHarness{caps: caps, on: on, logs: &bytes.Buffer{}} + now := time.Date(2026, 11, 18, 12, 0, 0, 0, time.UTC) + h.now = &now + h.k = NewKnowledgeAdviser(caps, on.Load, time.Second) + h.k.now = func() time.Time { return *h.now } + h.k.spawn = func(f func()) { f() } + h.k.Logger = slog.New(slog.NewTextHandler(h.logs, nil)) + return h +} + +func (h *adviserHarness) warnings() int { return strings.Count(h.logs.String(), "level=WARN") } + +var kickA = time.Date(2026, 11, 18, 11, 0, 0, 5, time.UTC) + +func pathScope() crux.KnowledgeScope { + return crux.KnowledgeScope{ + Kind: "path", Key: "src/crux/agent", Path: "src/crux/agent/manager.go", + Keywords: []string{"crux", "agent"}, Action: crux.KnowledgeActionEdit, PaneTail: "line one\nline two", + } +} + +func TestKnowledgeAdviserIsOffUntilTheHiveAdvertisesTheRoute(t *testing.T) { + h := newAdviserHarness(t) + h.on.Store(false) + if p := h.k.Policy("developer"); p != (crux.KnowledgeAdvisorPolicy{}) { + t.Fatalf("policy with the route not advertised = %+v", p) + } + if got := h.k.AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Fatalf("advice with the route not advertised: %+v", got) + } + if n := len(h.caps.calls()); n != 0 { + t.Fatalf("an unadvertised route was called %d times", n) + } + + var nilAdviser *KnowledgeAdviser + if p := nilAdviser.Policy("developer"); p.Enabled { + t.Error("nil adviser enabled") + } + if got := nilAdviser.AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Error("nil adviser advised") + } + if got := NewKnowledgeAdviser(nil, func() bool { return true }, 0).Policy("developer"); got.Enabled { + t.Error("an adviser with no capabilities enabled") + } + if got := NewKnowledgeAdviser(struct{}{}, func() bool { return true }, 0).AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Error("an adviser over capabilities with no route advised") + } + if got := NewKnowledgeAdviser(h.caps, nil, 0).Policy("developer"); got.Enabled { + t.Error("an adviser with no switch enabled") + } + if got := h.k.Advise("developer", pathScope()); got != nil { + t.Error("the kick-less seam must give no advice: the hive requires a kick identity") + } +} + +// Policy never waits on the hive: the first call starts a fetch and answers +// off; the next ones answer from the cache until it ages out. +func TestKnowledgeAdviserPolicyIsFetchedInTheBackgroundAndCached(t *testing.T) { + h := newAdviserHarness(t) + var pending []func() + h.k.spawn = func(f func()) { pending = append(pending, f) } + + if p := h.k.Policy("developer"); p.Enabled { + t.Fatalf("policy before the first answer = %+v, want off", p) + } + if p := h.k.Policy("developer"); p.Enabled || len(pending) != 1 { + t.Fatalf("a second call while a fetch is in flight started another: %d pending", len(pending)) + } + pending[0]() + want := crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, Cooldown: 45 * time.Second, WantsPaneTail: true, PaneLines: 30} + if p := h.k.Policy("developer"); p != want { + t.Fatalf("policy = %+v, want %+v", p, want) + } + calls := h.caps.calls() + if len(calls) != 1 || !calls[0].PolicyOnly || calls[0].Agent != "developer" || !calls[0].KickAt.IsZero() || calls[0].Scope.Key != "" { + t.Fatalf("policy request = %+v", calls) + } + + *h.now = h.now.Add(DefaultKnowledgePolicyTTL - time.Second) + h.k.Policy("developer") + if len(pending) != 1 { + t.Fatal("refetched inside the TTL") + } + *h.now = h.now.Add(2 * time.Second) + if p := h.k.Policy("developer"); p != want { + t.Fatalf("a stale policy is still served while the refresh runs: %+v", p) + } + if len(pending) != 2 { + t.Fatalf("no refetch after the TTL: %d", len(pending)) + } + + // The hive turns the advisor off for the agent: the next refresh says so. + h.caps.mu.Lock() + h.caps.resp.Policy = callback.KnowledgeAdvisorPolicy{} + h.caps.mu.Unlock() + pending[1]() + if p := h.k.Policy("developer"); p.Enabled { + t.Fatalf("policy after the hive disabled the agent = %+v", p) + } + // Policies are per agent. + if p := h.k.Policy("scanner"); p.Enabled { + t.Fatalf("another agent inherited a policy: %+v", p) + } + if got := h.k.Policy(""); got.Enabled { + t.Fatal("empty agent enabled") + } +} + +func TestKnowledgeAdviserPolicyFetchFailureKeepsTheAdvisorOff(t *testing.T) { + h := newAdviserHarness(t) + h.k.Policy("developer") // spawn is inline: the fetch succeeded + if p := h.k.Policy("developer"); !p.Enabled { + t.Fatal("setup: policy not fetched") + } + h.caps.mu.Lock() + h.caps.err = fmt.Errorf("%w: hive away", callback.ErrUnavailable) + h.caps.mu.Unlock() + for i := 0; i < 3; i++ { + *h.now = h.now.Add(DefaultKnowledgePolicyTTL + time.Second) + h.k.Policy("developer") + } + if p := h.k.Policy("developer"); p.Enabled { + t.Fatalf("policy after failed fetches = %+v, want off", p) + } + if n := h.warnings(); n != 1 { + t.Fatalf("policy failures logged %d warnings, want one per outage:\n%s", n, h.logs) + } + // Recovery turns it back on. + h.caps.mu.Lock() + h.caps.err = nil + h.caps.mu.Unlock() + *h.now = h.now.Add(DefaultKnowledgePolicyTTL + time.Second) + h.k.Policy("developer") + if p := h.k.Policy("developer"); !p.Enabled { + t.Fatal("policy did not recover") + } +} + +func TestKnowledgeAdviserSendsTheScopeAndRedactsEverything(t *testing.T) { + h := newAdviserHarness(t) + h.caps.resp.Advice = []callback.KnowledgeAdvice{ + {Slug: "a", Title: "A", Summary: "sum", Ref: "ref"}, + {Slug: "", Title: "no slug"}, + {Slug: "b", Title: "B"}, + } + scope := pathScope() + scope.PaneTail = "run with token " + testToken + "\nnext line" + scope.Key = "src/" + testToken + scope.Path = "src/" + testToken + "/a.go" + scope.Keywords = []string{testToken, "crux"} + + got := h.k.AdviseForKick("developer", kickA, scope) + if len(got) != 2 || got[0] != (crux.KnowledgeAdvice{Slug: "a", Title: "A", Summary: "sum", Ref: "ref"}) || got[1].Slug != "b" { + t.Fatalf("advice = %+v (an entry with no slug is dropped)", got) + } + calls := h.caps.calls() + if len(calls) != 1 { + t.Fatalf("calls = %d", len(calls)) + } + req := calls[0] + if req.Agent != "developer" || !req.KickAt.Equal(kickA) || req.PolicyOnly { + t.Errorf("request identity = %+v", req) + } + if req.Scope.Kind != "path" || req.Scope.Action != crux.KnowledgeActionEdit || req.Scope.Key == "" { + t.Errorf("scope = %+v", req.Scope) + } + wire := fmt.Sprintf("%+v", req) + if strings.Contains(wire, "ghp_abcdefghijklmnopqrstuvwxyz") || !strings.Contains(req.Scope.PaneTail, "ghp_abc***") { + t.Errorf("a token crossed to the hive unredacted: %s", wire) + } + // The response's policy is now the agent's current one. + if p := h.k.Policy("developer"); p.PaneLines != 30 || !p.Enabled { + t.Errorf("policy after an advise = %+v", p) + } +} + +func TestKnowledgeAdviserCapsAdviceLines(t *testing.T) { + h := newAdviserHarness(t) + for i := 0; i < maxKnowledgeAdviceLines+4; i++ { + h.caps.resp.Advice = append(h.caps.resp.Advice, callback.KnowledgeAdvice{Slug: fmt.Sprintf("s%d", i), Title: "t"}) + } + if got := h.k.AdviseForKick("developer", kickA, pathScope()); len(got) != maxKnowledgeAdviceLines { + t.Fatalf("advice lines = %d, want %d", len(got), maxKnowledgeAdviceLines) + } +} + +// Any failure is no advice, and a kick logs one warning however many scopes +// and ticks fail; the next kick logs its own. +func TestKnowledgeAdviserFailsClosedWithOneWarningPerKick(t *testing.T) { + h := newAdviserHarness(t) + for name, err := range map[string]error{ + "unavailable": fmt.Errorf("%w: down", callback.ErrUnavailable), + "forbidden": fmt.Errorf("%w: stale kick", callback.ErrForbidden), + "rate limited": fmt.Errorf("%w: slow", callback.ErrRateLimited), + "unauthorized": callback.ErrUnauthorized, + "not enabled": callback.ErrNotConfigured, + } { + h.caps.mu.Lock() + h.caps.err = err + h.caps.mu.Unlock() + if got := h.k.AdviseForKick("developer", kickA.Add(time.Duration(len(name))*time.Hour), pathScope()); got != nil { + t.Errorf("%s: advice %+v", name, got) + } + } + + h2 := newAdviserHarness(t) + h2.caps.err = fmt.Errorf("%w: down", callback.ErrUnavailable) + h2.caps.resp.Advice = []callback.KnowledgeAdvice{{Slug: "x", Title: "t"}} + for i := 0; i < 5; i++ { + if got := h2.k.AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Fatalf("advice on a failed call: %+v", got) + } + } + if n := h2.warnings(); n != 1 { + t.Fatalf("one kick logged %d warnings, want 1:\n%s", n, h2.logs) + } + if got := h2.k.AdviseForKick("developer", kickA.Add(time.Minute), pathScope()); got != nil { + t.Fatal("advice on a failed call in the next kick") + } + if n := h2.warnings(); n != 2 { + t.Fatalf("two kicks logged %d warnings, want 2:\n%s", n, h2.logs) + } + if strings.Contains(h2.logs.String(), testToken) { + t.Fatalf("a token reached the log:\n%s", h2.logs) + } + // Another agent's failure is its own warning. + h2.k.AdviseForKick("scanner", kickA, pathScope()) + if n := h2.warnings(); n != 3 { + t.Fatalf("a second agent logged %d warnings in total, want 3", n) + } +} + +func TestKnowledgeAdviserNeedsAgentAndKick(t *testing.T) { + h := newAdviserHarness(t) + if got := h.k.AdviseForKick("", kickA, pathScope()); got != nil { + t.Error("advised an empty agent") + } + if got := h.k.AdviseForKick("developer", time.Time{}, pathScope()); got != nil { + t.Error("advised without a kick identity") + } + if n := len(h.caps.calls()); n != 0 { + t.Fatalf("an unidentified request reached the hive %d times", n) + } +} + +// A hive that cannot be reached is no advice and exactly one warning for the +// kick, over the real client, with no panic and no wait past the timeout. +func TestKnowledgeAdviserUnreachableOverTheClient(t *testing.T) { + dir, err := os.MkdirTemp("", "hcapk") + if err != nil { + t.Fatal(err) + } + defer func() { _ = os.RemoveAll(dir) }() + c, err := callback.NewClient("unix://"+filepath.Join(dir, "nobody.sock"), "") + if err != nil { + t.Fatal(err) + } + var logs bytes.Buffer + k := NewKnowledgeAdviser(c, func() bool { return true }, 200*time.Millisecond) + k.Logger = slog.New(slog.NewTextHandler(&logs, nil)) + start := time.Now() + for i := 0; i < 3; i++ { + if got := k.AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Fatalf("advice from an unreachable hive: %+v", got) + } + } + if time.Since(start) > 5*time.Second { + t.Error("calls blocked past the timeout") + } + if n := strings.Count(logs.String(), "level=WARN"); n != 1 { + t.Fatalf("unreachable hive logged %d warnings for one kick, want 1:\n%s", n, logs.String()) + } + if c.Status().Reachable { + t.Errorf("client status = %+v, want unreachable", c.Status()) + } +} + +// policyAdvise is a hive that serves a policy snapshot and the knowledge +// route. +type policyAdvise struct { + *policyDirect + advise *fakeAdviseCaps +} + +func (p policyAdvise) AdviseKnowledge(ctx context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + return p.advise.AdviseKnowledge(ctx, req) +} + +// The adviser a Set carries is gated by the policy snapshot's flag, so a hive +// that never sets it keeps the runtime exactly as it was: no call is made. +func TestSetKnowledgeAdviserFollowsTheSnapshotFlag(t *testing.T) { + hive := policyAdvise{policyDirect: &policyDirect{direct: &direct{}}, advise: &fakeAdviseCaps{}} + hive.advise.resp.Policy = callback.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 1} + s := New(hive, 0) + s.Knowledge.spawn = func(f func()) { f() } + if s.Knowledge == nil || s.Policy.KnowledgeAdvise() { + t.Fatal("a Set must carry an adviser that is off before any snapshot") + } + if got := s.Knowledge.Policy("developer"); got.Enabled { + t.Fatalf("policy before any snapshot = %+v", got) + } + if _, err := s.Policy.Refresh(context.Background()); err != nil { + t.Fatal(err) + } + if s.Policy.KnowledgeAdvise() || s.Knowledge.Policy("developer").Enabled { + t.Fatal("a snapshot without the flag turned the adviser on") + } + if got := s.Knowledge.AdviseForKick("developer", kickA, pathScope()); got != nil { + t.Fatal("advised while the hive does not advertise the route") + } + if n := len(hive.advise.calls()); n != 0 { + t.Fatalf("the route was called %d times while not advertised", n) + } + + hive.set(callback.Policy{KnowledgeAdvise: true}, nil) + if _, err := s.Policy.Refresh(context.Background()); err != nil { + t.Fatal(err) + } + if !s.Policy.KnowledgeAdvise() { + t.Fatal("the snapshot flag was not read") + } + s.Knowledge.Policy("developer") + if got := s.Knowledge.Policy("developer"); !got.Enabled || got.MaxPerKick != 1 { + t.Fatalf("policy after the hive advertised the route = %+v", got) + } + + // The hive switches the route off again: the adviser goes quiet at once. + hive.set(callback.Policy{}, nil) + if _, err := s.Policy.Refresh(context.Background()); err != nil { + t.Fatal(err) + } + if got := s.Knowledge.Policy("developer"); got.Enabled { + t.Fatalf("policy after the hive switched the route off = %+v", got) + } + before := len(hive.advise.calls()) + if got := s.Knowledge.AdviseForKick("developer", kickA, pathScope()); got != nil || len(hive.advise.calls()) != before { + t.Fatal("advised after the hive stopped advertising the route") + } + var nilPolicy *Policy + if nilPolicy.KnowledgeAdvise() { + t.Fatal("nil policy advertised the route") + } +} diff --git a/src/crux/knowledge_advice.go b/src/crux/knowledge_advice.go index 1f754e9161..9169b17b86 100644 --- a/src/crux/knowledge_advice.go +++ b/src/crux/knowledge_advice.go @@ -77,3 +77,16 @@ type KnowledgeAdviser interface { // result is dropped if the agent's kick has changed by the time it returns. Advise(agent string, scope KnowledgeScope) []KnowledgeAdvice } + +// KickBoundKnowledgeAdviser is a KnowledgeAdviser that wants the identity of +// the kick a scope was observed in: the agent's LastKick when the runtime +// queued the scope. The runtime calls AdviseForKick instead of Advise when +// the adviser implements it. The in-process adviser has no use for it (it +// shares the runtime's address space and the runtime drops stale results +// itself); the sidecar callback adviser sends it so the hive can refuse a +// call that names a kick the agent is no longer in (hivecommons/hive#17157). +type KickBoundKnowledgeAdviser interface { + KnowledgeAdviser + // AdviseForKick is Advise for the kick that started at kickAt. + AdviseForKick(agent string, kickAt time.Time, scope KnowledgeScope) []KnowledgeAdvice +} diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index 71dd452daa..41d3663bbe 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -238,6 +238,57 @@ kicks form a control group with the same selection, and compare the two arms' outcomes. Lower `holdout_percent` once the comparison is settled; `mode: off` returns to phase 1 at any time. +### Sidecar runtimes (`knowledge.sidecar_advise`) + +A runtime in sidecar mode (`crux serve --hive-callback`) has no knowledge store +and must never hold the inference credentials the ranking pass spends, so it +gets the advisor over the hive's runtime-callback endpoint +(`POST /v1/knowledge/advise`, hivecommons/hive#17157). **It is off by default**: +with `knowledge.sidecar_advise: false` (or unset) the route answers `404 +not_configured`, the hive does not advertise the `knowledge_advise` capability +or set `knowledge_advise` in its policy snapshot, the runtime installs no +adviser, and a sidecar runtime behaves exactly as it did before the route +existed. Turn it on in Settings, Knowledge (applies without a restart), or in +`hive.yaml`; it also needs `knowledge.enabled` and `knowledge.advisor`. + +```yaml +knowledge: + enabled: true + advisor: true + sidecar_advise: true # default false +``` + +- **What crosses.** The runtime sends `{agent, kick_at, scope}`: the scope an + agent entered (kind, key, relative path, keywords, action) and, only when the + policy asks for a pane tail (`advisor_llm` on), the last `pane_lines` lines + of its scrollback. The pane tail is redacted with `logscrub.RedactPaneTokens` + in the runtime before it is sent and again on the hive. The hive answers the + advice lines (slug, title, summary, ref) and the delivery policy for the + agent (`enabled`, `max_per_kick`, `cooldown_ms`, `wants_pane_tail`, + `pane_lines`). No inference credential, endpoint or model setting is ever + sent to the runtime, and the model's `reason` never leaves the hive: the + runtime types only the advice fields, through phase 1's delivery primitive + and gates. +- **Same chain.** The hive runs whichever adviser chain it runs in-process: + phase 1 alone, or phase 1 wrapped by the ranking pass with its budgets, + hive-wide pacer and holdout arm. The request cannot widen the scope or pick + an entry; candidates still come from the Primer under `knowledge.agent_scopes`. +- **Authorization.** Served only on the runtime-callback server, behind the + same bearer token as the other `/v1/*` callbacks (an unauthenticated call + gets the same `401`). The hive checks that the named agent belongs to the + calling runtime and that `kick_at` is that agent's current kick; a mismatch is + `403` and no advice. +- **Limits.** One call in flight per agent and at most two evaluations of a + scope per kick (a third is `429`), at most 128 scopes per kick. A pane tail + longer than `pane_lines` is `400`; a body over 64 KiB is `413`; an unknown + scope kind or action, an absolute path or one with `..`, and over-long keys + or keywords are `400`. +- **Fail closed.** A transport error, a non-2xx answer, a malformed body or the + knob being off means no advice. The runtime logs one warning per kick, not + per poll tick. The runtime fetches each agent's policy in the background + (`policy_only` call, cached 30 s) and never waits on the hive on the poll + tick, so a hive that is away leaves the advisor off, not stalled. + ## 3. AGENTS.md / CLAUDE.md: injected by Hive, not read natively Each agent's CLI starts in `/data/agents/` (`crux.DefaultWorkDir`), diff --git a/src/docs/api-reference/knowledge.md b/src/docs/api-reference/knowledge.md index c6d70149fd..2b22349dd2 100644 --- a/src/docs/api-reference/knowledge.md +++ b/src/docs/api-reference/knowledge.md @@ -45,8 +45,8 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `POST` | `/api/config/knowledge/connectors/{name}/sync` | Owner only | Start an immediate background sync of one connector | `pkg/dashboard/api.go` | | `GET` | `/api/config/knowledge/agent-scopes` | Dashboard auth/session | Per-agent knowledge scopes (`knowledge.agent_scopes`: layers, repos, types, tags, include_states) ([docs](../knowledge-toc.md#per-agent-scopes)) | `pkg/dashboard/api.go` | | `PUT` | `/api/config/knowledge/agent-scopes` | Owner only | Replace `knowledge.agent_scopes` after validating layer and state names; persisted and audited as `config_knowledge_agent_scopes` | `pkg/dashboard/api.go` | -| `GET` | `/api/config/knowledge/pipeline` | Owner only | Scalar bead synthesizer, curator, code map and primer settings, plus the read-only engine, vault paths and primer merge strategy ([docs](../settings.md#knowledge)) | `pkg/dashboard/api.go` | -| `PUT` | `/api/config/knowledge/pipeline` | Owner only | Update those settings after `config.ValidateKnowledgePipeline`; 0 or empty restores the default; the bead synthesizer switch applies at once, the rest after a restart; audited as `config_knowledge_pipeline` | `pkg/dashboard/api.go` | +| `GET` | `/api/config/knowledge/pipeline` | Owner only | Scalar bead synthesizer, curator, code map and primer settings and `knowledge.sidecar_advise`, plus the read-only engine, advisor flag, vault paths and primer merge strategy ([docs](../settings.md#knowledge)) | `pkg/dashboard/api.go` | +| `PUT` | `/api/config/knowledge/pipeline` | Owner only | Update those settings after `config.ValidateKnowledgePipeline`; 0 or empty restores the default; the bead synthesizer switch and `sidecar_advise` apply at once, the rest after a restart; audited as `config_knowledge_pipeline` | `pkg/dashboard/api.go` | | `GET` | `/api/knowledge/git-sources` | Dashboard auth/session | Git Sources List | `pkg/dashboard/api.go:417` | | `POST` | `/api/knowledge/git-sources` | Owner only | Git Sources Connect | `pkg/dashboard/api.go:418` | | `DELETE` | `/api/knowledge/git-sources` | Owner only | Git Sources Disconnect | `pkg/dashboard/api.go:419` | diff --git a/src/docs/crux-serve.md b/src/docs/crux-serve.md index 89ac35085b..bc7a034330 100644 --- a/src/docs/crux-serve.md +++ b/src/docs/crux-serve.md @@ -215,6 +215,7 @@ entry. The remaining setters, all on the same callback endpoint: | `SetAppAuth` | `POST /v1/tokens` with `{agent, tier}` and no repos (installation-wide, what `AppAuth.ScopedToken(tier)` mints in-process); `hivecap.AppTokenWriter` writes the token in place (`O_TRUNC`, `0600`) to the agent's existing cache file and nowhere else, never logging it. `HIVE_PROXY_INJECT_GH_AUTH` is refused in sidecar mode (`ErrProxyInjectionUnsupported`) rather than writing the real token | cache file untouched; the agent keeps its last token or runs read-only | | `SetAgentMint` | `POST /v1/tokens/mint` (`agent_mint`); a hive with mint disabled answers `404 not_configured`, which the writer maps to the in-process "mint off" contract (`""`, no error) | no mint token | | `SetBobAPIKeyResolver`, `SetBobKeySourceResolver` | `GET /v1/bob/credential` (`bob`); cached 1 min runtime-side, a failed refresh serves the stale value for at most 2 min | empty key and source | +| `SetKnowledgeAdviser` | `POST /v1/knowledge/advise` (`knowledge_advise`), served only while the hive's `knowledge.sidecar_advise` is on (default off); the runtime installs `hivecap.KnowledgeAdviser` only once the policy snapshot's `knowledge_advise` flag says so, and fetches each agent's delivery policy with a `policy_only` call (cached 30 s). The request is `{agent, kick_at, scope}` (the scope's pane tail already redacted); the answer is advice lines plus the policy. The hive checks the agent belongs to this runtime and `kick_at` is its current kick (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). No model setting or credential crosses to the runtime | no advice, one warning per kick | | `SetSpanStarter` | — in-process-only: a span is a Go value wrapping a call in one address space. The sidecar's manager starts spans on the OpenTelemetry global tracer (a no-op without an exporter in the runtime's process); trajectory events do not depend on it | n/a | The proxy seams are carried the same way: `hivecap.Set.{Accounting, diff --git a/src/docs/design/crux.md b/src/docs/design/crux.md index f49da7f593..b942ce1e27 100644 --- a/src/docs/design/crux.md +++ b/src/docs/design/crux.md @@ -708,7 +708,7 @@ setter is added without one. | `SetLinearCredentialResolver`, `SetSandboxPushMinter`, `SetSandboxPRClient` | callback | `GET /v1/linear/credential`, `POST /v1/tokens`, `POST /v1/pulls` (stage 2) | | observers (`SetKickOutcomeObserver`, `SetPauseTransitionObserver`, `SetRelaunchObserver`, `SetPersistPauseCallback`, `SetRecordPromptCallback`, `SetSandboxAuditCallback`, `SetAuditSink`, `SetConditionReporter`) | event | the `/v1/events` stream (stage 3); conditions also `POST /v1/conditions` | | `SetSpanStarter` | in-process-only | a span is a Go value wrapping a call in one address space. The sidecar's manager starts spans on the OpenTelemetry global tracer (a no-op without an exporter in the runtime's process); trajectory events do not depend on it | -| `SetKnowledgeAdviser` | in-process-only | the mid-task knowledge advisor (#17052) asks hive's `knowledge.Primer` off the poll tick (one call in flight per agent) for every new scope an agent enters; phase 1 keeps it in-process (the sidecar runs with no adviser, so the feature is off there) until a `/v1/knowledge/advise` capability is worth its round trip | +| `SetKnowledgeAdviser` | callback | `POST /v1/knowledge/advise` (`knowledge_advise` capability, off by default behind `knowledge.sidecar_advise`; #17157): the runtime sends the scope an agent entered plus its redacted pane tail, the hive runs the same adviser chain it runs in-process and answers advice lines plus the delivery policy. The policy snapshot's `knowledge_advise` flag decides whether the runtime installs `hivecap.KnowledgeAdviser` at all, so with the knob off nothing changes. Authenticated like every `/v1/*` callback; the hive checks the agent belongs to the calling runtime and the kick is its current kick (403), refuses a second call in flight per agent and a third evaluation of one scope per kick (429), rejects a pane tail over `pane_lines` (400) and a body over 64 KiB (413). Fails closed: any error is no advice, one warning per kick | No setter is served from a `runtime:` config key: every value is already resolved hive-side from the live config, so a reload reaches the runtime @@ -719,6 +719,8 @@ on its next poll, and the callback pattern was already there. - [x] `SetInferenceCallbacks` over the `inference_routes` family and `SetSandboxMutationBoundary` over the `effects` family (#14394). - [x] `SetSpanStarter` documented as in-process-only (#14394). +- [x] `SetKnowledgeAdviser` over `POST /v1/knowledge/advise` (#17157), default + off. See [agent-knowledge-and-memory.md](../agent-knowledge-and-memory.md#sidecar-runtimes-knowledgesidecar_advise). - [x] `SetAgentMint` / `SetAppAuth` / Bob key resolvers as callback-backed writers (`crux/hivecap/credentials.go`, #14404). Tokens are never logged and go only to the existing per-agent cache path; all three fail closed diff --git a/src/docs/knowledge-curator.md b/src/docs/knowledge-curator.md index 8ecf7dcba0..93e37463b3 100644 --- a/src/docs/knowledge-curator.md +++ b/src/docs/knowledge-curator.md @@ -738,9 +738,9 @@ knowledge: negative `candidates`, `pane_lines` or `timeout_s` are load errors. Without `knowledge.advisor_llm` (or with `mode: off`) the advisor is the -pure phase-1 matcher with no model in the loop. The advisor is -wired only when the agent runtime runs in-process; the `crux serve` sidecar -has no adviser in this phase. +pure phase-1 matcher with no model in the loop. A `crux serve` sidecar gets no +adviser unless `knowledge.sidecar_advise` is on (default off); see +[Sidecar runtimes](agent-knowledge-and-memory.md#sidecar-runtimes-knowledgesidecar_advise). ## Open questions diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index af28a9d2d9..1652661339 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -325,7 +325,8 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `knowledge.connectors[].scope` (`notion`) | All pages shared with the integration; `max_pages` `2000`; `full_sync_every` `10`. | Optional `root_page_ids` / `database_ids`; `include_archived` fetches bodies of archived pages. Pages must be shared with the internal integration (••• → Connections). Requests are spaced 350 ms apart. | | `knowledge.publish` | Unset (`connector` empty): publishing off. | One-way mirror of curator-promoted facts into one connector target: `connector` (a `knowledge.connectors` name whose type can publish), `layers` (`project`/`org`/`community`; personal is never published), `root`, optional `include_types`, `dry_run`, `propose_via`. Facts are read from each layer's `knowledge.layers[].path`. Started at boot (a bad connector logs `knowledge publish mirror disabled` and leaves publishing off); state in `/data/knowledge/connector-state/_publish`. Status in the `publish` object of `GET /api/knowledge/connectors`; owner-only `POST /api/knowledge/publish/sync`. See [knowledge-connectors.md](../knowledge-connectors.md#publish-mirror). | | `knowledge.bead_synthesizer.publish` | Off (`enabled: false`). | Publishes synthesized facts into a repository through one PR on `hive/bead-synth-knowledge`: `enabled`, `repo` (empty = `project.primary_repo`), `path` (default `docs/knowledge/`; `.hive/knowledge/` is the alternative; relative, no `..`), `base_branch` (empty = repo default branch), `mode` (`pr` default or `commit`), `cadence` (`per_run` default or `daily`). ACMM L<=4 hives publish via PR only; `commit` is warned about and still opens a PR. See [knowledge-curator.md](../knowledge-curator.md#repository-publish-knowledgebead_synthesizerpublish). | -| `knowledge.advisor` | Off (`false`). | Mid-task knowledge advisor (#17052): on each poll tick, when a running agent's pane shows work in a scope (directory prefix or `gh pr`/`issue`/`run` family) that was not on screen at kick time, matching knowledge entries the kick did not already carry are typed into the session as one `šŸ“š Knowledge:` line each. `advisor_max_per_kick` (default `3`) caps lines per kick; `advisor_exclude_agents` lists agent or replica-family names to skip. Never typed during a tool call, after the turn ends, while a human is attached, or in the `crux serve` sidecar. Each delivery lands in prompt history with trigger `knowledge-advisor`. See [knowledge-curator.md](../knowledge-curator.md#mid-task-knowledge-advisor-knowledgeadvisor). | +| `knowledge.advisor` | Off (`false`). | Mid-task knowledge advisor (#17052): on each poll tick, when a running agent's pane shows work in a scope (directory prefix or `gh pr`/`issue`/`run` family) that was not on screen at kick time, matching knowledge entries the kick did not already carry are typed into the session as one `šŸ“š Knowledge:` line each. `advisor_max_per_kick` (default `3`) caps lines per kick; `advisor_exclude_agents` lists agent or replica-family names to skip. Never typed during a tool call, after the turn ends, or while a human is attached. A `crux serve` sidecar runtime gets it only with `knowledge.sidecar_advise` on. Each delivery lands in prompt history with trigger `knowledge-advisor`. See [knowledge-curator.md](../knowledge-curator.md#mid-task-knowledge-advisor-knowledgeadvisor). | +| `knowledge.sidecar_advise` | Off (`false`). | Serve the mid-task knowledge advisor to a sidecar-mode runtime (#17157) over `POST /v1/knowledge/advise` on the runtime-callback endpoint, behind the same bearer token as the other `/v1/*` callbacks. Needs `knowledge.enabled` and `knowledge.advisor`. Off, the route answers `404 not_configured`, the hive does not advertise the `knowledge_advise` capability, and a sidecar runtime runs without the advisor as before. The hive runs the same adviser chain it runs in-process, so `advisor_llm` ranking and its budgets apply; no model setting or credential is sent to the runtime. Settings, Knowledge toggle; applies without a restart. See [agent-knowledge-and-memory.md](../agent-knowledge-and-memory.md#sidecar-runtimes-knowledgesidecar_advise). | | `variables.security.*` | Deny by default. | `allow_exec`, `allow_http`, and GitHub prompt-source allowlists are honored only from the trusted seed, not dashboard overlays. | | `agents..prompt_source` (size cap) | 96 KiB (`promptsrc.DefaultMaxPromptBytes`); `HIVE_PROMPT_SOURCE_MAX_BYTES` overrides it. | A fetched kick template over the cap is **rejected whole, not truncated** ([#12130](https://github.com/hivecommons/hive/issues/12130)): the kick uses the last successfully fetched copy if there is one, otherwise the ordinary `kick_template` → pack → convention → embedded-default chain, and the scheduler logs `prompt from GitHub exceeds size cap; REJECTED whole (not truncated), falling back` with `repo`, `path`, `size_bytes` and `cap_bytes`. Saving an agent whose source is over the cap fails in the dashboard with the same sizes rather than baking a cut-off policy. A half-policy is a policy with its closing rules missing; no remote policy is the safer failure. Every shipped template fits with >2Ɨ headroom (`TestShippedTemplatesFitUnderCap`). | | `data.claude_sessions_dir` | `/data/home/.claude/projects` | Where the dashboard reads Claude Code session JSONL for per-agent token/cost accounting. When it has the canonical `/.claude/projects` shape the scan also covers every per-agent `/agents/*/.claude/projects` ([#17031](https://github.com/hivecommons/hive/issues/17031)); `data.bob_sessions_dir` and `data.copilot_sessions_dir` behave the same way. Point it at the agents' real session directory if you relocate `HOME`. The `.claude` tree is also where Claude Code keeps its persistent auto-memory; see [agent-knowledge-and-memory.md](../agent-knowledge-and-memory.md) for which per-agent home paths are fleet-shared and what `clear_on_kick` does and does not clear. | diff --git a/src/docs/settings.md b/src/docs/settings.md index 22f529e0fb..612099afc0 100644 --- a/src/docs/settings.md +++ b/src/docs/settings.md @@ -89,7 +89,7 @@ The other features on this tab (OpenTelemetry export, external execution, auto-p ## Knowledge -Whether the public read-only knowledge MCP endpoint is on, the knowledge pipeline, and the external knowledge connectors. The **Knowledge pipeline** block sets the bead synthesizer (schedule, target layer, minimum confidence, per-cycle fact and GitHub API caps, bead retention), scheduled curator promotion (schedule, threshold, source and target layers), repository code maps (schedule, layer, size cap) and the kick primer's fact and byte caps. Turning the bead synthesizer on or off applies at once; the other pipeline settings apply after a restart, and 0 or empty restores the default. The engine, the vault paths and the primer merge strategy are shown read-only because they are set in `hive.yaml`. The repositories to map and the primer priority list stay yaml-only. See [Knowledge curator](knowledge-curator.md) and [Knowledge connectors](knowledge-connectors.md). +Whether the public read-only knowledge MCP endpoint is on, the knowledge pipeline, and the external knowledge connectors. The **Knowledge pipeline** block opens with the **Mid-task advisor for sidecar runtimes** switch (`knowledge.sidecar_advise`, off by default, applies at once, needs `knowledge.advisor` set in `hive.yaml`; see [Sidecar runtimes](agent-knowledge-and-memory.md#sidecar-runtimes-knowledgesidecar_advise)), then sets the bead synthesizer (schedule, target layer, minimum confidence, per-cycle fact and GitHub API caps, bead retention), scheduled curator promotion (schedule, threshold, source and target layers), repository code maps (schedule, layer, size cap) and the kick primer's fact and byte caps. Turning the bead synthesizer on or off applies at once; the other pipeline settings apply after a restart, and 0 or empty restores the default. The engine, the vault paths and the primer merge strategy are shown read-only because they are set in `hive.yaml`. The repositories to map and the primer priority list stay yaml-only. See [Knowledge curator](knowledge-curator.md) and [Knowledge connectors](knowledge-connectors.md). ## Meeting attendee diff --git a/src/pkg/config/knowledge_advisor_test.go b/src/pkg/config/knowledge_advisor_test.go index a5e06bf2f9..c07c6bd0bd 100644 --- a/src/pkg/config/knowledge_advisor_test.go +++ b/src/pkg/config/knowledge_advisor_test.go @@ -1,6 +1,7 @@ package config import ( + "strings" "testing" "gopkg.in/yaml.v3" @@ -73,3 +74,56 @@ func TestKnowledgeAdvisor_ParseAndDefault(t *testing.T) { t.Errorf("advisor_max_per_kick = %d, want %d", cfg.Knowledge.AdvisorMaxPerKick, DefaultKnowledgeAdvisorMaxPerKick) } } + +// knowledge.sidecar_advise (hivecommons/hive#17157): the sidecar route is off +// unless knowledge, the advisor and the knob are all on, and the knob alone +// defaults off. +func TestKnowledgeSidecarAdvise(t *testing.T) { + var k KnowledgeConfig + if err := yaml.Unmarshal([]byte("sidecar_advise: true\n"), &k); err != nil { + t.Fatal(err) + } + if !k.SidecarAdvise { + t.Fatalf("sidecar_advise not parsed: %+v", k) + } + out, err := yaml.Marshal(KnowledgeConfig{}) + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(out), "sidecar_advise") { + t.Errorf("an unset sidecar_advise is written to hive.yaml: %s", out) + } + + cfg := &Config{ + Project: ProjectConfig{Org: "o", Repos: []string{"r"}}, + GitHub: GitHubConfig{Token: "t"}, + AgentRuntimeConfig: AgentRuntimeConfig{Agents: map[string]AgentConfig{"a": {Backend: "claude"}}}, + Knowledge: KnowledgeConfig{Enabled: true, Advisor: true}, + } + cfg.applyDefaults() + if cfg.Knowledge.SidecarAdvise || cfg.KnowledgeSidecarAdviseEnabled() { + t.Error("sidecar_advise must default off, even with the advisor on") + } + + tests := []struct { + name string + k KnowledgeConfig + want bool + }{ + {"all on", KnowledgeConfig{Enabled: true, Advisor: true, SidecarAdvise: true}, true}, + {"knob off", KnowledgeConfig{Enabled: true, Advisor: true}, false}, + {"advisor off", KnowledgeConfig{Enabled: true, SidecarAdvise: true}, false}, + {"knowledge off", KnowledgeConfig{Advisor: true, SidecarAdvise: true}, false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := (&Config{Knowledge: tt.k}).KnowledgeSidecarAdviseEnabled(); got != tt.want { + t.Errorf("KnowledgeSidecarAdviseEnabled() = %v, want %v", got, tt.want) + } + }) + } + var nilCfg *Config + if nilCfg.KnowledgeSidecarAdviseEnabled() { + t.Error("nil config enabled the route") + } +} diff --git a/src/pkg/config/knowledge_config.go b/src/pkg/config/knowledge_config.go index 4ee173924a..93e19ef3e7 100644 --- a/src/pkg/config/knowledge_config.go +++ b/src/pkg/config/knowledge_config.go @@ -59,6 +59,14 @@ type KnowledgeConfig struct { // AdvisorLLM configures the optional model-ranked advisor pass // (hivecommons/hive#17054). Ignored unless Advisor is true. AdvisorLLM AdvisorLLMConfig `yaml:"advisor_llm,omitempty"` + // SidecarAdvise turns on POST /v1/knowledge/advise on the hive's runtime + // callback endpoint, so a sidecar-mode runtime gets the mid-task adviser + // too (hivecommons/hive#17157). Default false: the route is absent, the + // hive does not advertise it, and a sidecar runtime runs without the + // advisor as before. Ignored unless Enabled and Advisor are true; the + // route serves whichever chain the hive runs in-process (phase 1, with + // the advisor_llm ranking pass when configured). + SidecarAdvise bool `yaml:"sidecar_advise,omitempty"` } // PublicKnowledgeConfig is the dashboard-persisted owner override for the @@ -386,6 +394,13 @@ func (c *Config) KnowledgeAdvisorEnabledFor(agent string) bool { return true } +// KnowledgeSidecarAdviseEnabled reports whether the hive serves the sidecar +// knowledge-advise route: knowledge, the advisor and knowledge.sidecar_advise +// are all on. knowledge.sidecar_advise itself defaults off. +func (c *Config) KnowledgeSidecarAdviseEnabled() bool { + return c != nil && c.Knowledge.Enabled && c.Knowledge.Advisor && c.Knowledge.SidecarAdvise +} + func (c *Config) KnowledgeAgentScope(agent string) (KnowledgeAgentScope, bool) { if c == nil || len(c.Knowledge.AgentScopes) == 0 || agent == "" { return KnowledgeAgentScope{}, false diff --git a/src/pkg/config/testdata/agent_runtime_golden.json b/src/pkg/config/testdata/agent_runtime_golden.json index 4bea69b2cc..a52b7c543a 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -571,7 +571,8 @@ "BudgetOverride": false, "HoldoutPercent": 0, "OnError": "" - } + }, + "SidecarAdvise": false }, "inbox": { "spek": {}, diff --git a/src/pkg/cruxhost/cruxhost.go b/src/pkg/cruxhost/cruxhost.go index c06c16a179..b4c0355c80 100644 --- a/src/pkg/cruxhost/cruxhost.go +++ b/src/pkg/cruxhost/cruxhost.go @@ -135,6 +135,23 @@ type Deps struct { // in-process "mint off" contract. Mint AgentMintIssuer Bob BobResolver + // Knowledge is the hive's mid-task knowledge adviser behind POST + // /v1/knowledge/advise (hivecommons/hive#17157); nil means the capability + // is absent. Even when set, the capability exists only while its Enabled + // reports true (knowledge.sidecar_advise, default off). + Knowledge KnowledgeAdviseService +} + +// KnowledgeAdviseService answers a sidecar runtime's mid-task knowledge +// requests. Enabled is read on every request and on every policy snapshot, so +// a config reload turns the route on or off without a restart; while it is +// false the route answers 404 not_configured and the capability is not +// advertised. The checks that make the exchange safe (agent and kick +// identity, request limits, rate limits) belong to the implementation; it +// reports them as callback.ErrForbidden, ErrInvalidRequest and ErrRateLimited. +type KnowledgeAdviseService interface { + Enabled() bool + AdviseKnowledge(ctx context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) } // AgentMintIssuer is crux.AgentMintIssuer restated so cruxhost does not @@ -156,13 +173,14 @@ type Capabilities struct { } var ( - _ callback.Capabilities = (*Capabilities)(nil) - _ callback.Configured = (*Capabilities)(nil) - _ callback.PolicySource = (*Capabilities)(nil) - _ callback.InferenceRouter = (*Capabilities)(nil) - _ callback.EffectBoundary = (*Capabilities)(nil) - _ callback.AgentMinter = (*Capabilities)(nil) - _ callback.BobCredentials = (*Capabilities)(nil) + _ callback.Capabilities = (*Capabilities)(nil) + _ callback.Configured = (*Capabilities)(nil) + _ callback.PolicySource = (*Capabilities)(nil) + _ callback.InferenceRouter = (*Capabilities)(nil) + _ callback.EffectBoundary = (*Capabilities)(nil) + _ callback.AgentMinter = (*Capabilities)(nil) + _ callback.BobCredentials = (*Capabilities)(nil) + _ callback.KnowledgeAdvisers = (*Capabilities)(nil) ) // New builds the capability set over deps. @@ -202,6 +220,8 @@ func (c *Capabilities) Configured(capability string) bool { return c.deps.Mint != nil case callback.CapabilityBob: return c.deps.Bob != nil + case callback.CapabilityKnowledgeAdvise: + return c.knowledgeAdviseOn() } return false } @@ -418,9 +438,26 @@ func (c *Capabilities) Policy(context.Context) (callback.Policy, error) { } p := c.deps.Policy() p.RepoAutoMerge = c.deps.RepoAutoMerge != nil + p.KnowledgeAdvise = c.knowledgeAdviseOn() return p, nil } +// knowledgeAdviseOn reports whether POST /v1/knowledge/advise is being +// served right now. +func (c *Capabilities) knowledgeAdviseOn() bool { + return c.deps.Knowledge != nil && c.deps.Knowledge.Enabled() +} + +// AdviseKnowledge is callback.KnowledgeAdvisers.AdviseKnowledge. A hive whose +// knowledge.sidecar_advise is off answers not_configured, as one with no +// adviser at all. +func (c *Capabilities) AdviseKnowledge(ctx context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + if !c.knowledgeAdviseOn() { + return callback.KnowledgeAdviseResponse{}, callback.ErrNotConfigured + } + return c.deps.Knowledge.AdviseKnowledge(ctx, req) +} + // RepoAutoMergeEnabled answers the per-repository auto-merge switch. func (c *Capabilities) RepoAutoMergeEnabled(_ context.Context, repo string) (bool, error) { if c.deps.Policy == nil || c.deps.RepoAutoMerge == nil { diff --git a/src/pkg/cruxhost/cruxhost_test.go b/src/pkg/cruxhost/cruxhost_test.go index 6c9d97dcc7..e5a2360e30 100644 --- a/src/pkg/cruxhost/cruxhost_test.go +++ b/src/pkg/cruxhost/cruxhost_test.go @@ -496,3 +496,111 @@ func TestAgentMintAndBobCapabilities(t *testing.T) { } } } + +// fakeKnowledge is a KnowledgeAdviseService whose switch the test flips, as a +// config reload flips knowledge.sidecar_advise. +type fakeKnowledge struct { + mu sync.Mutex + on bool + reqs []callback.KnowledgeAdviseRequest + err error +} + +func (f *fakeKnowledge) set(on bool) { + f.mu.Lock() + defer f.mu.Unlock() + f.on = on +} + +func (f *fakeKnowledge) Enabled() bool { + f.mu.Lock() + defer f.mu.Unlock() + return f.on +} + +func (f *fakeKnowledge) AdviseKnowledge(_ context.Context, req callback.KnowledgeAdviseRequest) (callback.KnowledgeAdviseResponse, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.reqs = append(f.reqs, req) + if f.err != nil { + return callback.KnowledgeAdviseResponse{}, f.err + } + return callback.KnowledgeAdviseResponse{ + Advice: []callback.KnowledgeAdvice{{Slug: "s", Title: "t"}}, + Policy: callback.KnowledgeAdvisorPolicy{Enabled: true}, + }, nil +} + +// The knowledge capability exists only while the service says it is enabled, +// read live: no dep, or a dep that is switched off, is not configured, is not +// in the policy snapshot, and is not dispatched. +func TestKnowledgeAdviseFollowsTheLiveSwitch(t *testing.T) { + ctx := context.Background() + req := callback.KnowledgeAdviseRequest{Agent: "developer", PolicyOnly: true} + + none := New(Deps{Policy: func() callback.Policy { return callback.Policy{} }}) + if none.Configured(callback.CapabilityKnowledgeAdvise) { + t.Error("knowledge advise configured with no dep") + } + if _, err := none.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrNotConfigured) { + t.Errorf("no dep: err = %v", err) + } + if pol, err := none.Policy(ctx); err != nil || pol.KnowledgeAdvise { + t.Errorf("no dep policy = %+v, %v", pol, err) + } + + svc := &fakeKnowledge{} + caps := New(Deps{Knowledge: svc, Policy: func() callback.Policy { return callback.Policy{} }}) + if caps.Configured(callback.CapabilityKnowledgeAdvise) { + t.Error("knowledge advise configured while the switch is off") + } + if _, err := caps.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrNotConfigured) { + t.Errorf("switch off: err = %v", err) + } + if pol, err := caps.Policy(ctx); err != nil || pol.KnowledgeAdvise { + t.Errorf("switch off policy = %+v, %v", pol, err) + } + if len(svc.reqs) != 0 { + t.Fatalf("an off switch reached the service: %+v", svc.reqs) + } + + svc.set(true) + if !caps.Configured(callback.CapabilityKnowledgeAdvise) { + t.Error("knowledge advise not configured while the switch is on") + } + if pol, err := caps.Policy(ctx); err != nil || !pol.KnowledgeAdvise { + t.Errorf("switch on policy = %+v, %v", pol, err) + } + resp, err := caps.AdviseKnowledge(ctx, req) + if err != nil || len(resp.Advice) != 1 || resp.Advice[0].Slug != "s" || len(svc.reqs) != 1 || svc.reqs[0].Agent != "developer" { + t.Fatalf("response = %+v, %v, reqs %+v", resp, err, svc.reqs) + } + svc.err = callback.ErrForbidden + if _, err := caps.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrForbidden) { + t.Errorf("service refusal = %v, want it passed through", err) + } + + // Over the socket the same switch is the route and the health list. + c, _ := serve(t, Deps{Knowledge: svc}) + svc.err = nil + health, err := c.Health(ctx) + if err != nil || !containsString(health.Capabilities, callback.CapabilityKnowledgeAdvise) { + t.Fatalf("health = %+v, %v", health, err) + } + svc.set(false) + if health, err = c.Health(ctx); err != nil || containsString(health.Capabilities, callback.CapabilityKnowledgeAdvise) { + t.Fatalf("health after switching off = %+v, %v", health, err) + } + if _, err := c.AdviseKnowledge(ctx, req); !errors.Is(err, callback.ErrNotConfigured) { + t.Errorf("route after switching off: err = %v", err) + } +} + +func containsString(list []string, s string) bool { + for _, v := range list { + if v == s { + return true + } + } + return false +} diff --git a/src/pkg/dashboard/api_config_knowledge_pipeline.go b/src/pkg/dashboard/api_config_knowledge_pipeline.go index ebab4a5036..3f538f5043 100644 --- a/src/pkg/dashboard/api_config_knowledge_pipeline.go +++ b/src/pkg/dashboard/api_config_knowledge_pipeline.go @@ -12,8 +12,11 @@ import ( // knowledge.code_maps and knowledge.primer keys. Every field is a pointer so // an absent key leaves the config untouched; 0 or "" restores the default. // Local vault paths and the engine are display-only -// and not accepted here. +// and not accepted here. SidecarAdvise is knowledge.sidecar_advise +// (hivecommons/hive#17157): whether the hive serves the mid-task advisor to a +// sidecar-mode runtime. It applies without a restart. type knowledgePipelineBody struct { + SidecarAdvise *bool `json:"sidecar_advise"` BeadSynthesizer *struct { Enabled *bool `json:"enabled"` Schedule *string `json:"schedule"` @@ -64,6 +67,10 @@ func trimLower(p *string) string { return strings.ToLower(strings.TrimSpace(*p)) func (b knowledgePipelineBody) prepare(cur config.KnowledgeConfig) (func(*config.KnowledgeConfig), error) { var probe config.KnowledgeConfig var steps []func(*config.KnowledgeConfig) + if b.SidecarAdvise != nil { + v := *b.SidecarAdvise + steps = append(steps, func(k *config.KnowledgeConfig) { k.SidecarAdvise = v }) + } if bs := b.BeadSynthesizer; bs != nil { if bs.Enabled != nil { v := *bs.Enabled @@ -269,6 +276,10 @@ func knowledgePipelineResponse(cfg *config.Config) map[string]interface{} { return map[string]interface{}{ // Display-only: the engine picks the knowledge backend at boot. "engine": k.Engine, + // knowledge.sidecar_advise is editable; knowledge.advisor, which it + // needs, stays yaml-only and is shown so the control can say so. + "sidecar_advise": k.SidecarAdvise, + "advisor": k.Advisor, "bead_synthesizer": map[string]interface{}{ "publish": k.BeadSynthesizer.Publish.WithDefaults(), "enabled": k.BeadSynthesizer.IsEnabled(), @@ -341,7 +352,7 @@ func (s *Server) handleKnowledgePipelineGet(w http.ResponseWriter, r *http.Reque } // handleKnowledgePipelinePut updates the scalar bead synthesizer, curator, -// code map and primer keys (owner-only). The request is validated before +// code map and primer keys and knowledge.sidecar_advise (owner-only). The request is validated before // anything is applied, then persisted and audited. The bead synthesizer // switch starts or stops the running synthesizer at once, as // PUT /api/knowledge/bead-synthesizer/enabled does; every other key is read diff --git a/src/pkg/dashboard/knowledge_settings_parity_test.go b/src/pkg/dashboard/knowledge_settings_parity_test.go index f7114d0968..421a197f8d 100644 --- a/src/pkg/dashboard/knowledge_settings_parity_test.go +++ b/src/pkg/dashboard/knowledge_settings_parity_test.go @@ -4,6 +4,7 @@ import ( "encoding/json" "net/http" "net/http/httptest" + "os" "strings" "testing" @@ -233,6 +234,7 @@ func TestParityBatch8SettingsRenderEveryKey(t *testing.T) { body := extractJSFunction(t, html, "renderKnowledgePipelineBody") for _, c := range []struct{ yaml, id string }{ + {"knowledge.sidecar_advise", "sa-enabled"}, {"knowledge.bead_synthesizer.enabled", "bs-enabled"}, {"knowledge.bead_synthesizer.schedule", "bs-schedule"}, {"knowledge.bead_synthesizer.target_layer", "bs-target_layer"}, @@ -291,3 +293,85 @@ func TestParityBatch8SettingsRenderEveryKey(t *testing.T) { t.Error("the Knowledge tab does not render the pipeline section") } } + +// knowledge.sidecar_advise (hivecommons/hive#17157) is saved through the same +// pipeline PUT: off by default, a PUT that does not carry it leaves it alone, +// it applies to the live config at once, and the GET reports it with the +// advisor flag it depends on. +func TestKnowledgePipelineSidecarAdvise(t *testing.T) { + s := covApiServer(t) + k := &s.deps.Config.Knowledge + + rec := doOwnerGet(s, knowledgePipelinePath) + if rec.Code != http.StatusOK { + t.Fatalf("GET: %d", rec.Code) + } + var resp map[string]any + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatal(err) + } + if resp["sidecar_advise"] != false || resp["advisor"] != false || k.SidecarAdvise { + t.Fatalf("default GET = %s (sidecar_advise must default off)", rec.Body.String()) + } + + if rec := doPut(s, knowledgePipelinePath, map[string]any{"primer": map[string]any{"max_facts": 7}}); rec.Code != http.StatusOK { + t.Fatalf("unrelated PUT: %d", rec.Code) + } + if k.SidecarAdvise { + t.Fatal("a PUT that does not carry sidecar_advise turned it on") + } + + k.Advisor = true + rec = doPut(s, knowledgePipelinePath, map[string]any{"sidecar_advise": true}) + if rec.Code != http.StatusOK { + t.Fatalf("PUT true: %d, %s", rec.Code, rec.Body.String()) + } + if !k.SidecarAdvise { + t.Fatalf("sidecar_advise not applied: %+v", *k) + } + resp = nil + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatal(err) + } + if resp["sidecar_advise"] != true || resp["advisor"] != true { + t.Fatalf("PUT response = %s", rec.Body.String()) + } + if k.Primer.MaxFacts != 7 { + t.Fatal("setting sidecar_advise changed an unrelated key") + } + + if rec := doPut(s, knowledgePipelinePath, map[string]any{"sidecar_advise": false}); rec.Code != http.StatusOK { + t.Fatalf("PUT false: %d", rec.Code) + } + if k.SidecarAdvise { + t.Fatal("sidecar_advise not turned off") + } +} + +// The Settings control for knowledge.sidecar_advise sits at the top of the +// Knowledge tab's pipeline section, saves through the pipeline PUT as a +// top-level key, and says it applies without a restart. +func TestKnowledgeSidecarAdviseControl(t *testing.T) { + html := indexHTML(t) + body := extractJSFunction(t, html, "renderKnowledgePipelineBody") + if !strings.Contains(body, "toggle('sa-enabled', ") || !strings.Contains(body, "'knowledge.sidecar_advise'") { + t.Error("the pipeline section has no knowledge.sidecar_advise toggle with its YAML hint") + } + if strings.Index(body, "'sa-enabled'") > strings.Index(body, "'bs-enabled'") { + t.Error("the sidecar advisor toggle is not the first control in the pipeline section") + } + if !strings.Contains(body, "knowledge.advisor is off in hive.yaml") { + t.Error("the control does not say it needs knowledge.advisor") + } + save := extractJSFunction(t, html, "saveKnowledgePipeline") + if !strings.Contains(save, "['top', 'sidecar_advise', 'sa-enabled', 'bool']") || !strings.Contains(save, "body[key] = v") { + t.Error("saveKnowledgePipeline does not send sidecar_advise as a top-level key") + } + allow, err := os.ReadFile("settings_parity_allowlist.txt") + if err != nil { + t.Fatal(err) + } + if strings.Contains(string(allow), "knowledge.sidecar_advise") { + t.Error("knowledge.sidecar_advise must have a Settings control, not an allowlist entry") + } +} diff --git a/src/pkg/dashboard/static-src/js/config-state.js b/src/pkg/dashboard/static-src/js/config-state.js index 6998158f9a..935e451031 100644 --- a/src/pkg/dashboard/static-src/js/config-state.js +++ b/src/pkg/dashboard/static-src/js/config-state.js @@ -140,7 +140,7 @@ { tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Context7 auto-import', key: 'knowledge.context7.auto_import', lazy: true, text: 'context7 auto import startup libraries knowledge.context7.auto_import[].id knowledge.context7.auto_import[].query' }, { tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Plaud voice notes connector', key: 'knowledge.connectors', lazy: true, text: 'plaud voice notes recordings transcript summary mcp oauth connect npx @plaud-ai/mcp command since_days max_files include_audio tags knowledge.connectors' }, { tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Wispr Flow dictation connector', key: 'knowledge.connectors', lazy: true, text: 'wispr flow wisprflow dictation voice history flow.sqlite sqlite export path since_days max_items min_words group apps include_raw tags knowledge.connectors' }, - { tab: 'Knowledge', section: 'Knowledge pipeline', label: 'Bead synthesizer, curator, code maps and primer', key: 'knowledge.bead_synthesizer.enabled', lazy: true, text: 'knowledge pipeline bead synthesizer wiki facts schedule hourly daily confidence target layer facts per cycle api calls vault retention archive beads high priority dependents curator auto promote threshold promotion from to code maps repository layer max bytes primer facts merge strategy engine public read-only mcp knowledge.engine knowledge.public.enabled knowledge.bead_synthesizer.enabled knowledge.bead_synthesizer.schedule knowledge.bead_synthesizer.min_confidence knowledge.bead_synthesizer.target_layer knowledge.bead_synthesizer.max_facts_per_cycle knowledge.bead_synthesizer.max_api_calls_per_cycle knowledge.bead_synthesizer.vault_path publish to repository knowledge.bead_synthesizer.publish.enabled knowledge.bead_synthesizer.publish.repo knowledge.bead_synthesizer.publish.path knowledge.bead_synthesizer.publish.base_branch knowledge.bead_synthesizer.publish.mode knowledge.bead_synthesizer.publish.cadence knowledge.bead_synthesizer.retention_policy.max_beads knowledge.bead_synthesizer.retention_policy.archive_after_synth_days knowledge.bead_synthesizer.retention_policy.high_priority_retain_days knowledge.bead_synthesizer.retention_policy.preserve_with_deps knowledge.curator.enabled knowledge.curator.schedule knowledge.curator.auto_promote_threshold knowledge.curator.promote_from knowledge.curator.promote_to knowledge.code_maps.enabled knowledge.code_maps.schedule knowledge.code_maps.layer knowledge.code_maps.max_bytes knowledge.code_maps.vault_path knowledge.primer.max_facts knowledge.primer.max_bytes knowledge.primer.merge_strategy' }, + { tab: 'Knowledge', section: 'Knowledge pipeline', label: 'Bead synthesizer, curator, code maps and primer', key: 'knowledge.bead_synthesizer.enabled', lazy: true, text: 'knowledge pipeline bead synthesizer wiki facts schedule hourly daily confidence target layer facts per cycle api calls vault retention archive beads high priority dependents curator auto promote threshold promotion from to code maps repository layer max bytes primer facts merge strategy engine public read-only mcp knowledge.engine knowledge.public.enabled mid-task advisor sidecar runtime callback knowledge.sidecar_advise knowledge.bead_synthesizer.enabled knowledge.bead_synthesizer.schedule knowledge.bead_synthesizer.min_confidence knowledge.bead_synthesizer.target_layer knowledge.bead_synthesizer.max_facts_per_cycle knowledge.bead_synthesizer.max_api_calls_per_cycle knowledge.bead_synthesizer.vault_path publish to repository knowledge.bead_synthesizer.publish.enabled knowledge.bead_synthesizer.publish.repo knowledge.bead_synthesizer.publish.path knowledge.bead_synthesizer.publish.base_branch knowledge.bead_synthesizer.publish.mode knowledge.bead_synthesizer.publish.cadence knowledge.bead_synthesizer.retention_policy.max_beads knowledge.bead_synthesizer.retention_policy.archive_after_synth_days knowledge.bead_synthesizer.retention_policy.high_priority_retain_days knowledge.bead_synthesizer.retention_policy.preserve_with_deps knowledge.curator.enabled knowledge.curator.schedule knowledge.curator.auto_promote_threshold knowledge.curator.promote_from knowledge.curator.promote_to knowledge.code_maps.enabled knowledge.code_maps.schedule knowledge.code_maps.layer knowledge.code_maps.max_bytes knowledge.code_maps.vault_path knowledge.primer.max_facts knowledge.primer.max_bytes knowledge.primer.merge_strategy' }, { tab: 'Forge App', section: 'Forge App', label: 'GitHub API quota, PR scans and authorship', key: 'github.api_reserve', lazy: true, text: 'github api quota reserve critical agent reserve floor pr detail cache ttl etag cache size mb entries conditional request 304 graphql batch page size app authored prs bot signed commits forge api url docs installation oauth client token github.api_reserve github.api_critical github.agent_reserve_floor github.etag_cache_max_mb github.etag_cache_max_entries github.pr_detail_ttl_s github.graphql_pr_batch github.graphql_pr_batch_page_size github.app_authored_prs github.app_signed_commits github.forge github.api_url github.docs_installation_id github.oauth_client_id github.token github.key_file' }, ]; let _settingsSearch = { active: false, query: '', previousTab: '', index: null, bound: false }; diff --git a/src/pkg/dashboard/static-src/js/config-tabs.js b/src/pkg/dashboard/static-src/js/config-tabs.js index 3613b7f9b8..98574e0eae 100644 --- a/src/pkg/dashboard/static-src/js/config-tabs.js +++ b/src/pkg/dashboard/static-src/js/config-tabs.js @@ -629,7 +629,13 @@ `; const schedules = d.schedules || ['hourly', 'daily']; const layers = d.layers || ['personal', 'project', 'org', 'community']; + const advisorOn = !!d.advisor; return ` +
+
Mid-task advisor for sidecar runtimes
+ ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs knowledge.advisor, which stays in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} + ${advisorOn ? '' : '
knowledge.advisor is off in hive.yaml, so this has no effect until it is on.
'} +
Bead synthesizer
${toggle('bs-enabled', 'Synthesize completed beads into wiki facts', 'knowledge.bead_synthesizer.enabled', bs.enabled, 'on by default; starts or stops the running synthesizer.', true, 'Turns completed beads (and their merged PRs) into wiki facts on a schedule. On unless set to false. Saving starts or stops the running synthesizer at once.')} @@ -705,6 +711,7 @@ async function saveKnowledgePipeline() { const d = _kpState.data || {}; const cur = { + top: { sidecar_advise: d.sidecar_advise }, bead_synthesizer: d.bead_synthesizer || {}, publish: (d.bead_synthesizer || {}).publish || {}, retention_policy: (d.bead_synthesizer || {}).retention_policy || {}, @@ -713,6 +720,7 @@ primer: d.primer || {} }; const fields = [ + ['top', 'sidecar_advise', 'sa-enabled', 'bool'], ['bead_synthesizer', 'enabled', 'bs-enabled', 'bool'], ['bead_synthesizer', 'schedule', 'bs-schedule', 'str'], ['bead_synthesizer', 'target_layer', 'bs-target_layer', 'str'], @@ -743,7 +751,9 @@ ]; const body = {}; const put = (group, key, v) => { - if (group === 'retention_policy' || group === 'publish') { + if (group === 'top') { + body[key] = v; + } else if (group === 'retention_policy' || group === 'publish') { body.bead_synthesizer = body.bead_synthesizer || {}; body.bead_synthesizer[group] = body.bead_synthesizer[group] || {}; body.bead_synthesizer[group][key] = v; @@ -782,7 +792,7 @@ if (!res.ok) throw new Error(data.error || ('HTTP ' + res.status)); _kpState = { loaded: true, error: '', data: data }; const bsKeys = Object.keys(body.bead_synthesizer || {}); - const liveOnly = Object.keys(body).length === 1 && bsKeys.length === 1 && bsKeys[0] === 'enabled'; + const liveOnly = Object.keys(body).every(k => k === 'sidecar_advise' || (k === 'bead_synthesizer' && bsKeys.length === 1 && bsKeys[0] === 'enabled')); showToast(liveOnly ? 'Knowledge settings saved' : 'Knowledge settings saved — restart the hive to apply them', 'success'); const el = document.getElementById('kp-pipeline-root'); if (el) el.innerHTML = renderKnowledgePipelineBody(); diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index 46e7363171..f256ec26ee 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -64845,7 +64845,7 @@

Configure LiteLLM

{ tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Context7 auto-import', key: 'knowledge.context7.auto_import', lazy: true, text: 'context7 auto import startup libraries knowledge.context7.auto_import[].id knowledge.context7.auto_import[].query' }, { tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Plaud voice notes connector', key: 'knowledge.connectors', lazy: true, text: 'plaud voice notes recordings transcript summary mcp oauth connect npx @plaud-ai/mcp command since_days max_files include_audio tags knowledge.connectors' }, { tab: 'Knowledge', section: 'Knowledge Integrations', label: 'Wispr Flow dictation connector', key: 'knowledge.connectors', lazy: true, text: 'wispr flow wisprflow dictation voice history flow.sqlite sqlite export path since_days max_items min_words group apps include_raw tags knowledge.connectors' }, - { tab: 'Knowledge', section: 'Knowledge pipeline', label: 'Bead synthesizer, curator, code maps and primer', key: 'knowledge.bead_synthesizer.enabled', lazy: true, text: 'knowledge pipeline bead synthesizer wiki facts schedule hourly daily confidence target layer facts per cycle api calls vault retention archive beads high priority dependents curator auto promote threshold promotion from to code maps repository layer max bytes primer facts merge strategy engine public read-only mcp knowledge.engine knowledge.public.enabled knowledge.bead_synthesizer.enabled knowledge.bead_synthesizer.schedule knowledge.bead_synthesizer.min_confidence knowledge.bead_synthesizer.target_layer knowledge.bead_synthesizer.max_facts_per_cycle knowledge.bead_synthesizer.max_api_calls_per_cycle knowledge.bead_synthesizer.vault_path publish to repository knowledge.bead_synthesizer.publish.enabled knowledge.bead_synthesizer.publish.repo knowledge.bead_synthesizer.publish.path knowledge.bead_synthesizer.publish.base_branch knowledge.bead_synthesizer.publish.mode knowledge.bead_synthesizer.publish.cadence knowledge.bead_synthesizer.retention_policy.max_beads knowledge.bead_synthesizer.retention_policy.archive_after_synth_days knowledge.bead_synthesizer.retention_policy.high_priority_retain_days knowledge.bead_synthesizer.retention_policy.preserve_with_deps knowledge.curator.enabled knowledge.curator.schedule knowledge.curator.auto_promote_threshold knowledge.curator.promote_from knowledge.curator.promote_to knowledge.code_maps.enabled knowledge.code_maps.schedule knowledge.code_maps.layer knowledge.code_maps.max_bytes knowledge.code_maps.vault_path knowledge.primer.max_facts knowledge.primer.max_bytes knowledge.primer.merge_strategy' }, + { tab: 'Knowledge', section: 'Knowledge pipeline', label: 'Bead synthesizer, curator, code maps and primer', key: 'knowledge.bead_synthesizer.enabled', lazy: true, text: 'knowledge pipeline bead synthesizer wiki facts schedule hourly daily confidence target layer facts per cycle api calls vault retention archive beads high priority dependents curator auto promote threshold promotion from to code maps repository layer max bytes primer facts merge strategy engine public read-only mcp knowledge.engine knowledge.public.enabled mid-task advisor sidecar runtime callback knowledge.sidecar_advise knowledge.bead_synthesizer.enabled knowledge.bead_synthesizer.schedule knowledge.bead_synthesizer.min_confidence knowledge.bead_synthesizer.target_layer knowledge.bead_synthesizer.max_facts_per_cycle knowledge.bead_synthesizer.max_api_calls_per_cycle knowledge.bead_synthesizer.vault_path publish to repository knowledge.bead_synthesizer.publish.enabled knowledge.bead_synthesizer.publish.repo knowledge.bead_synthesizer.publish.path knowledge.bead_synthesizer.publish.base_branch knowledge.bead_synthesizer.publish.mode knowledge.bead_synthesizer.publish.cadence knowledge.bead_synthesizer.retention_policy.max_beads knowledge.bead_synthesizer.retention_policy.archive_after_synth_days knowledge.bead_synthesizer.retention_policy.high_priority_retain_days knowledge.bead_synthesizer.retention_policy.preserve_with_deps knowledge.curator.enabled knowledge.curator.schedule knowledge.curator.auto_promote_threshold knowledge.curator.promote_from knowledge.curator.promote_to knowledge.code_maps.enabled knowledge.code_maps.schedule knowledge.code_maps.layer knowledge.code_maps.max_bytes knowledge.code_maps.vault_path knowledge.primer.max_facts knowledge.primer.max_bytes knowledge.primer.merge_strategy' }, { tab: 'Forge App', section: 'Forge App', label: 'GitHub API quota, PR scans and authorship', key: 'github.api_reserve', lazy: true, text: 'github api quota reserve critical agent reserve floor pr detail cache ttl etag cache size mb entries conditional request 304 graphql batch page size app authored prs bot signed commits forge api url docs installation oauth client token github.api_reserve github.api_critical github.agent_reserve_floor github.etag_cache_max_mb github.etag_cache_max_entries github.pr_detail_ttl_s github.graphql_pr_batch github.graphql_pr_batch_page_size github.app_authored_prs github.app_signed_commits github.forge github.api_url github.docs_installation_id github.oauth_client_id github.token github.key_file' }, ]; let _settingsSearch = { active: false, query: '', previousTab: '', index: null, bound: false }; @@ -66464,7 +66464,13 @@

Configure LiteLLM

`; const schedules = d.schedules || ['hourly', 'daily']; const layers = d.layers || ['personal', 'project', 'org', 'community']; + const advisorOn = !!d.advisor; return ` +
+
Mid-task advisor for sidecar runtimes
+ ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs knowledge.advisor, which stays in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} + ${advisorOn ? '' : '
knowledge.advisor is off in hive.yaml, so this has no effect until it is on.
'} +
Bead synthesizer
${toggle('bs-enabled', 'Synthesize completed beads into wiki facts', 'knowledge.bead_synthesizer.enabled', bs.enabled, 'on by default; starts or stops the running synthesizer.', true, 'Turns completed beads (and their merged PRs) into wiki facts on a schedule. On unless set to false. Saving starts or stops the running synthesizer at once.')} @@ -66540,6 +66546,7 @@

Configure LiteLLM

async function saveKnowledgePipeline() { const d = _kpState.data || {}; const cur = { + top: { sidecar_advise: d.sidecar_advise }, bead_synthesizer: d.bead_synthesizer || {}, publish: (d.bead_synthesizer || {}).publish || {}, retention_policy: (d.bead_synthesizer || {}).retention_policy || {}, @@ -66548,6 +66555,7 @@

Configure LiteLLM

primer: d.primer || {} }; const fields = [ + ['top', 'sidecar_advise', 'sa-enabled', 'bool'], ['bead_synthesizer', 'enabled', 'bs-enabled', 'bool'], ['bead_synthesizer', 'schedule', 'bs-schedule', 'str'], ['bead_synthesizer', 'target_layer', 'bs-target_layer', 'str'], @@ -66578,7 +66586,9 @@

Configure LiteLLM

]; const body = {}; const put = (group, key, v) => { - if (group === 'retention_policy' || group === 'publish') { + if (group === 'top') { + body[key] = v; + } else if (group === 'retention_policy' || group === 'publish') { body.bead_synthesizer = body.bead_synthesizer || {}; body.bead_synthesizer[group] = body.bead_synthesizer[group] || {}; body.bead_synthesizer[group][key] = v; @@ -66617,7 +66627,7 @@

Configure LiteLLM

if (!res.ok) throw new Error(data.error || ('HTTP ' + res.status)); _kpState = { loaded: true, error: '', data: data }; const bsKeys = Object.keys(body.bead_synthesizer || {}); - const liveOnly = Object.keys(body).length === 1 && bsKeys.length === 1 && bsKeys[0] === 'enabled'; + const liveOnly = Object.keys(body).every(k => k === 'sidecar_advise' || (k === 'bead_synthesizer' && bsKeys.length === 1 && bsKeys[0] === 'enabled')); showToast(liveOnly ? 'Knowledge settings saved' : 'Knowledge settings saved — restart the hive to apply them', 'success'); const el = document.getElementById('kp-pipeline-root'); if (el) el.innerHTML = renderKnowledgePipelineBody(); From 56790d4481c0869a466a987a8a39b9b27e2d0253 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 18 Nov 2026 18:22:15 -0500 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=90=9B=20dashboard:=20keep=20the=20ad?= =?UTF-8?q?visor=20yaml-only=20entry=20by=20not=20naming=20it=20in=20the?= =?UTF-8?q?=20sidecar=20switch=20help?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/pkg/dashboard/knowledge_settings_parity_test.go | 2 +- src/pkg/dashboard/static-src/js/config-tabs.js | 4 ++-- src/pkg/dashboard/static/index.html | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/pkg/dashboard/knowledge_settings_parity_test.go b/src/pkg/dashboard/knowledge_settings_parity_test.go index 421a197f8d..3896523bb5 100644 --- a/src/pkg/dashboard/knowledge_settings_parity_test.go +++ b/src/pkg/dashboard/knowledge_settings_parity_test.go @@ -360,7 +360,7 @@ func TestKnowledgeSidecarAdviseControl(t *testing.T) { if strings.Index(body, "'sa-enabled'") > strings.Index(body, "'bs-enabled'") { t.Error("the sidecar advisor toggle is not the first control in the pipeline section") } - if !strings.Contains(body, "knowledge.advisor is off in hive.yaml") { + if !strings.Contains(body, "The mid-task advisor is off in hive.yaml") { t.Error("the control does not say it needs knowledge.advisor") } save := extractJSFunction(t, html, "saveKnowledgePipeline") diff --git a/src/pkg/dashboard/static-src/js/config-tabs.js b/src/pkg/dashboard/static-src/js/config-tabs.js index 98574e0eae..09c407eeb2 100644 --- a/src/pkg/dashboard/static-src/js/config-tabs.js +++ b/src/pkg/dashboard/static-src/js/config-tabs.js @@ -633,8 +633,8 @@ return `
Mid-task advisor for sidecar runtimes
- ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs knowledge.advisor, which stays in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} - ${advisorOn ? '' : '
knowledge.advisor is off in hive.yaml, so this has no effect until it is on.
'} + ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs the mid-task advisor, which is switched on in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} + ${advisorOn ? '' : '
The mid-task advisor is off in hive.yaml, so this has no effect until it is on.
'}
Bead synthesizer
diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index f256ec26ee..74e4144f74 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -66468,8 +66468,8 @@

Configure LiteLLM

return `
Mid-task advisor for sidecar runtimes
- ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs knowledge.advisor, which stays in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} - ${advisorOn ? '' : '
knowledge.advisor is off in hive.yaml, so this has no effect until it is on.
'} + ${toggle('sa-enabled', 'Serve the mid-task knowledge advisor to a sidecar runtime', 'knowledge.sidecar_advise', d.sidecar_advise, 'off by default; with it off a sidecar runtime gets no advisor.', true, 'Lets a sidecar-mode runtime ask this hive for mid-task knowledge hints over the callback endpoint. Needs the mid-task advisor, which is switched on in hive.yaml. The hive runs the same advisor it runs in-process and sends no model settings or credentials to the runtime. Off unless turned on.')} + ${advisorOn ? '' : '
The mid-task advisor is off in hive.yaml, so this has no effect until it is on.
'}
Bead synthesizer
From cbb54266ab9b2f1c49935d063476afba809367b6 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 18 Nov 2026 18:30:09 -0500 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=90=9B=20dashboard:=20drop=20the=20st?= =?UTF-8?q?ray=20advisor=20key=20mention=20that=20broke=20the=20settings?= =?UTF-8?q?=20parity=20allowlist?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- src/pkg/dashboard/api_config_knowledge_pipeline.go | 4 ++-- src/pkg/dashboard/knowledge_settings_parity_test.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pkg/dashboard/api_config_knowledge_pipeline.go b/src/pkg/dashboard/api_config_knowledge_pipeline.go index 3f538f5043..d7bad09993 100644 --- a/src/pkg/dashboard/api_config_knowledge_pipeline.go +++ b/src/pkg/dashboard/api_config_knowledge_pipeline.go @@ -276,8 +276,8 @@ func knowledgePipelineResponse(cfg *config.Config) map[string]interface{} { return map[string]interface{}{ // Display-only: the engine picks the knowledge backend at boot. "engine": k.Engine, - // knowledge.sidecar_advise is editable; knowledge.advisor, which it - // needs, stays yaml-only and is shown so the control can say so. + // sidecar_advise is editable; the mid-task advisor switch it needs + // stays yaml-only and is shown so the control can say so. "sidecar_advise": k.SidecarAdvise, "advisor": k.Advisor, "bead_synthesizer": map[string]interface{}{ diff --git a/src/pkg/dashboard/knowledge_settings_parity_test.go b/src/pkg/dashboard/knowledge_settings_parity_test.go index 3896523bb5..ace1612bce 100644 --- a/src/pkg/dashboard/knowledge_settings_parity_test.go +++ b/src/pkg/dashboard/knowledge_settings_parity_test.go @@ -361,7 +361,7 @@ func TestKnowledgeSidecarAdviseControl(t *testing.T) { t.Error("the sidecar advisor toggle is not the first control in the pipeline section") } if !strings.Contains(body, "The mid-task advisor is off in hive.yaml") { - t.Error("the control does not say it needs knowledge.advisor") + t.Error("the control does not say it needs the mid-task advisor") } save := extractJSFunction(t, html, "saveKnowledgePipeline") if !strings.Contains(save, "['top', 'sidecar_advise', 'sa-enabled', 'bool']") || !strings.Contains(save, "body[key] = v") {