diff --git a/changelog.d/added-knowledge-advisor.md b/changelog.d/added-knowledge-advisor.md new file mode 100644 index 0000000000..0f17a693d3 --- /dev/null +++ b/changelog.d/added-knowledge-advisor.md @@ -0,0 +1 @@ +- Mid-task knowledge advisor (opt-in `knowledge.advisor`, default off): when a running agent's work enters a scope that was not on screen at kick time, the matching knowledge entries the kick did not already carry are typed into its session as one `📚 Knowledge:` line each, capped per kick (`knowledge.advisor_max_per_kick`), never during a tool call, with per-agent opt-out (`knowledge.advisor_exclude_agents`) and a `knowledge-advisor` prompt-history trigger for measurement (#17052) diff --git a/src/cmd/hive/agent_runtime_sidecar.go b/src/cmd/hive/agent_runtime_sidecar.go index 08bcc4b08c..016e2f4723 100644 --- a/src/cmd/hive/agent_runtime_sidecar.go +++ b/src/cmd/hive/agent_runtime_sidecar.go @@ -331,6 +331,14 @@ 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") +} + // SetInferenceRoute and ClearInferenceRoute are cruxhost.InferenceRouter: // the callback's end of SetInferenceCallbacks. A route that arrives before // boot has installed the closures is dropped and logged; the runtime's diff --git a/src/cmd/hive/knowledge_adviser.go b/src/cmd/hive/knowledge_adviser.go new file mode 100644 index 0000000000..c7c2f97d8b --- /dev/null +++ b/src/cmd/hive/knowledge_adviser.go @@ -0,0 +1,137 @@ +package main + +import ( + "context" + "log/slog" + "strings" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/knowledge" +) + +// Mid-task knowledge adviser (hivecommons/hive#17052): the hive side of the +// runtime's knowledge advisor. The runtime says which scope an agent just +// entered; this asks the same Primer the kick used, under the same +// knowledge.agent_scopes restriction, and hands back entries the kick did +// not already carry. + +const ( + // knowledgeAdviseTimeout bounds one adviser query. It runs on the agent's + // poll goroutine, so a slow wiki layer must not stall the poller. + knowledgeAdviseTimeout = 5 * time.Second + // knowledgeAdviseMaxPerScope caps how many entries one scope may queue; + // the runtime's per-kick cap is the real bound, this keeps the queue short. + knowledgeAdviseMaxPerScope = 2 + // knowledgeAdviseSummaryRunes caps the body text handed to the runtime. + knowledgeAdviseSummaryRunes = 300 +) + +type knowledgeAdviser struct { + cfg func() *config.Config + primer func() *knowledge.Primer + primed func(agent string) []string + logger *slog.Logger +} + +func newKnowledgeAdviser(b *boot) *knowledgeAdviser { + return &knowledgeAdviser{ + cfg: func() *config.Config { return b.cfg }, + primer: func() *knowledge.Primer { + if b.sched == nil { + return nil + } + return b.sched.GetPrimer() + }, + primed: func(agent string) []string { + if b.sched == nil { + return nil + } + return b.sched.KickPrimedSlugs(agent) + }, + logger: b.logger, + } +} + +// Policy reads the live config every call so a dashboard change applies to +// the next poll tick without a restart, like the other host resolvers. +func (a *knowledgeAdviser) Policy(agent string) crux.KnowledgeAdvisorPolicy { + cfg := a.cfg() + if cfg == nil || !cfg.KnowledgeAdvisorEnabledFor(agent) { + return crux.KnowledgeAdvisorPolicy{} + } + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: cfg.Knowledge.AdvisorMaxPerKick} +} + +// Advise searches the knowledge store for scope. Until #17045 lands the +// Primer has no kick context for paths, so the observed file goes in as the +// primer's file path and the scope's segments as keywords. +func (a *knowledgeAdviser) Advise(agent string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + primer := a.primer() + cfg := a.cfg() + if primer == nil || cfg == nil { + return nil + } + var paths []string + if scope.Path != "" { + paths = []string{scope.Path} + } + var agentScope *knowledge.TOCScope + if sc, ok := cfg.KnowledgeAgentScope(agent); ok { + s := knowledge.AgentScope(sc.Layers, sc.Repos, sc.Types, sc.Tags, sc.IncludeStates) + agentScope = &s + } + ctx, cancel := context.WithTimeout(context.Background(), knowledgeAdviseTimeout) + defer cancel() + primed := primer.PrimeScoped(ctx, agentScope, paths, scope.Keywords) + advice := selectKnowledgeAdvice(primed.Facts, a.primed(agent), knowledgeAdviseMaxPerScope) + a.logger.Debug("knowledge advisor: scope entered", + "agent", agent, "scope", scope.Key, "candidates", len(primed.Facts), "advice", len(advice)) + return advice +} + +// selectKnowledgeAdvice keeps the best-ranked facts not in exclude, up to +// limit, rendered for the runtime's one-line delivery. +func selectKnowledgeAdvice(facts []knowledge.Fact, exclude []string, limit int) []crux.KnowledgeAdvice { + skip := make(map[string]bool, len(exclude)) + for _, slug := range exclude { + skip[slug] = true + } + var out []crux.KnowledgeAdvice + for _, f := range facts { + if f.Slug == "" || skip[f.Slug] || strings.TrimSpace(f.Title) == "" { + continue + } + skip[f.Slug] = true + out = append(out, crux.KnowledgeAdvice{ + Slug: f.Slug, + Title: f.Title, + Summary: truncateRunes(strings.Join(strings.Fields(f.Body), " "), knowledgeAdviseSummaryRunes), + Ref: knowledgeAdviceRef(f), + }) + if len(out) >= limit { + break + } + } + return out +} + +// knowledgeAdviceRef is where the agent can read the whole entry: the first +// source document URL, else the knowledge entry id the dashboard serves. +func knowledgeAdviceRef(f knowledge.Fact) string { + for _, s := range f.Sources { + if s.DocURL != "" { + return s.DocURL + } + } + return "knowledge entry " + f.Slug +} + +func truncateRunes(s string, n int) string { + r := []rune(s) + if len(r) <= n { + return s + } + return strings.TrimSpace(string(r[:n-1])) + "…" +} diff --git a/src/cmd/hive/knowledge_adviser_test.go b/src/cmd/hive/knowledge_adviser_test.go new file mode 100644 index 0000000000..09c5db0bc9 --- /dev/null +++ b/src/cmd/hive/knowledge_adviser_test.go @@ -0,0 +1,83 @@ +package main + +import ( + "log/slog" + "reflect" + "strings" + "testing" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/knowledge" +) + +func TestSelectKnowledgeAdvice(t *testing.T) { + facts := []knowledge.Fact{ + {Slug: "primed", Title: "Already in the kick", Body: "x"}, + {Slug: "", Title: "No slug", Body: "x"}, + {Slug: "untitled", Title: " ", Body: "x"}, + {Slug: "tree", Title: "Re-pin the tree", Body: "line one\n\n line two " + strings.Repeat("w", 400), + Sources: []knowledge.Source{{PR: "1"}, {DocURL: "https://wiki/tree"}}}, + {Slug: "tree", Title: "Duplicate slug", Body: "x"}, + {Slug: "third", Title: "Third", Body: "short"}, + {Slug: "fourth", Title: "Fourth", Body: "never reached"}, + } + got := selectKnowledgeAdvice(facts, []string{"primed"}, 2) + if len(got) != 2 { + t.Fatalf("got %d advice: %+v", len(got), got) + } + if got[0].Slug != "tree" || got[0].Title != "Re-pin the tree" || got[0].Ref != "https://wiki/tree" { + t.Errorf("first = %+v", got[0]) + } + if !strings.HasPrefix(got[0].Summary, "line one line two w") || !strings.HasSuffix(got[0].Summary, "…") { + t.Errorf("summary = %q", got[0].Summary) + } + if n := len([]rune(got[0].Summary)); n > knowledgeAdviseSummaryRunes { + t.Errorf("summary is %d runes, cap %d", n, knowledgeAdviseSummaryRunes) + } + if got[1].Slug != "third" || got[1].Ref != "knowledge entry third" || got[1].Summary != "short" { + t.Errorf("second = %+v", got[1]) + } + if selectKnowledgeAdvice(nil, nil, 2) != nil { + t.Error("no facts should yield nil") + } +} + +func TestTruncateRunes(t *testing.T) { + if got := truncateRunes("héllo", 5); got != "héllo" { + t.Errorf("under cap = %q", got) + } + if got := truncateRunes("héllo wörld", 6); got != "héllo…" { + t.Errorf("over cap = %q", got) + } +} + +func TestKnowledgeAdviserPolicy(t *testing.T) { + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true, AdvisorMaxPerKick: 4}} + a := &knowledgeAdviser{cfg: func() *config.Config { return cfg }, logger: slog.Default()} + want := crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 4} + if got := a.Policy("developer"); !reflect.DeepEqual(got, want) { + t.Errorf("policy = %+v, want %+v", got, want) + } + cfg.Knowledge.Advisor = false + if got := a.Policy("developer"); got.Enabled { + t.Errorf("disabled policy = %+v", got) + } + a.cfg = func() *config.Config { return nil } + if got := a.Policy("developer"); got.Enabled { + t.Errorf("nil config policy = %+v", got) + } +} + +func TestKnowledgeAdviserAdvise_NoPrimerIsSilent(t *testing.T) { + cfg := &config.Config{Knowledge: config.KnowledgeConfig{Enabled: true, Advisor: true}} + a := &knowledgeAdviser{ + cfg: func() *config.Config { return cfg }, + primer: func() *knowledge.Primer { return nil }, + primed: func(string) []string { return nil }, + logger: slog.Default(), + } + if got := a.Advise("developer", crux.KnowledgeScope{Key: "src/a", Path: "src/a/x.go"}); got != nil { + t.Errorf("advice without a primer = %+v", got) + } +} diff --git a/src/cmd/hive/main.go b/src/cmd/hive/main.go index 32c5b7def2..e9f1479ed2 100644 --- a/src/cmd/hive/main.go +++ b/src/cmd/hive/main.go @@ -3919,6 +3919,11 @@ func (b *boot) bootWatchersWith(deps bootWatchersDeps) { // per-agent "Prompts" tab. Redaction and truncation happen inside the // store, before anything is written to the PVC. b.agentMgr.SetRecordPromptCallback(b.dashSrv.RecordPrompt) + // Mid-task knowledge advisor (#17052): the runtime asks this when an + // agent's pane first shows a scope its kick did not cover. Policy is read + // off the live config per call, so knowledge.advisor flips without a + // restart; the adviser itself is a no-op until SetPrimer has run. + b.agentMgr.SetKnowledgeAdviser(newKnowledgeAdviser(b)) // Feed agent lifecycle events (start, stop, launch FAILURE, backend/model // change) into the durable audit store behind the dashboard's Audit Log. diff --git a/src/crux/agent/knowledge_advisor.go b/src/crux/agent/knowledge_advisor.go new file mode 100644 index 0000000000..6cd0896605 --- /dev/null +++ b/src/crux/agent/knowledge_advisor.go @@ -0,0 +1,339 @@ +package agent + +import ( + "regexp" + "strings" + "sync" + "time" + + "github.com/hivecommons/hive/crux" +) + +// Mid-task knowledge advisor (hivecommons/hive#17052). +// +// The kick primer injects `# Relevant Knowledge` once, at kick time, from the +// issue titles and labels. Whatever the agent later turns out to touch gets +// nothing. The advisor closes that gap with the two things the runtime already +// has: the scrollback the poller captures every tick, and the typed-line +// primitive every other nudge uses. When the pane first shows a scope (a source +// directory, a `gh` command family) that was not there at the first post-kick +// poll, the hive-side adviser is asked for matching entries and each is typed +// into the live session as one `📚 Knowledge:` line, subject to a per-kick cap, +// a cooldown and the same never-type-over-a-human / never-splice-a-kick gates +// the CI-poll nudge honours. Default off (knowledge.advisor: false). + +const ( + // knowledgeAdvisorDefaultMaxPerKick is the per-kick delivery cap when the + // policy leaves it unset. + knowledgeAdvisorDefaultMaxPerKick = 3 + // knowledgeAdvisorDefaultCooldown is the minimum gap between two + // deliveries to one agent when the policy leaves it unset. Each line + // becomes a queued user turn in the CLI; back-to-back lines would read + // as an operator talking over the agent. + knowledgeAdvisorDefaultCooldown = 2 * time.Minute + // knowledgeAdvisorMaxScopeDepth is how many directory segments identify a + // path scope: src/crux/agent/manager.go opens "src/crux/agent". + knowledgeAdvisorMaxScopeDepth = 3 + // knowledgeAdvisorMaxSummary caps the body text in a delivered line. + knowledgeAdvisorMaxSummary = 300 + // knowledgeAdvisorTrigger is the prompt-history trigger each delivery is + // recorded under, so the dashboard shows it beside kicks. + knowledgeAdvisorTrigger = "knowledge-advisor" + knowledgeAdvisorKindPath = "path" + knowledgeAdvisorKindGH = "gh" +) + +// knowledgePathRe matches a relative file path with at least one directory and +// a file extension, as the CLIs print paths they read, edit or run against: +// "⏺ Read(src/crux/agent/manager.go)", "● Edit src/pkg/config/config.go", +// "$ cat src/docs/x.md". The leading class excludes URLs (":" and "//" never +// precede a match) and absolute paths (the segment before the first "/" must +// be a name). +var knowledgePathRe = regexp.MustCompile(`(?:^|[\s("'` + "`" + `=,\[])((?:\./)?(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_-][A-Za-z0-9_.-]*\.[A-Za-z0-9]{1,8})\b`) + +// knowledgeGHRe matches the GitHub CLI families worth a scope of their own. +var knowledgeGHRe = regexp.MustCompile(`\bgh (pr|issue|run|api|release|workflow)\b`) + +// knowledgeIgnoredDirs are path roots that are tooling, not the agent's work. +var knowledgeIgnoredDirs = map[string]bool{ + "node_modules": true, "vendor": true, ".git": true, "tmp": true, "proc": true, +} + +// knowledgeGenericSegments are directory names that carry no topic. +var knowledgeGenericSegments = map[string]bool{ + "src": true, "pkg": true, "cmd": true, "internal": true, "lib": true, "test": true, + "tests": true, "docs": true, "doc": true, "scripts": true, "static": true, "app": true, +} + +// knowledgeGHKeywords are the search terms a gh family contributes. +var knowledgeGHKeywords = map[string][]string{ + "pr": {"pull request", "pr"}, + "issue": {"issue", "triage"}, + "run": {"workflow run", "ci"}, + "api": {"github api", "rate limit"}, + "release": {"release", "tag"}, + "workflow": {"workflow", "ci"}, +} + +// knowledgeToolInFlightRe matches pane text the CLIs render only while a tool +// call is executing: Claude Code's collapsed "Running 1 shell command…", OMP's +// "⏺ Running… (esc to cancel)". Typing then would land inside the tool's +// output window, which is the one moment the advisor must not pick. +var knowledgeToolInFlightRe = regexp.MustCompile(`(?i)\brunning \d+ shell command|Running…|esc to cancel`) + +// knowledgeAdvisor holds the adviser and the per-agent, per-kick state. +type knowledgeAdvisor struct { + adviser crux.KnowledgeAdviser + now func() time.Time + mu sync.Mutex + agents map[string]*knowledgeKickState +} + +// knowledgeKickState is one agent's advisor state for one kick. It is +// replaced whenever LastKick moves, so a new kick starts clean without the +// kick path having to know the advisor exists. +type knowledgeKickState struct { + kickAt time.Time + baselined bool + seen map[string]bool // scope keys from the baseline or already handled + delivered map[string]bool // slugs typed this kick + count int + lastAt time.Time + pending []crux.KnowledgeAdvice +} + +// SetKnowledgeAdviser installs the hive-side matcher. A nil adviser turns the +// advisor off. It is an atomic store so the poller never takes m.mu for it. +func (m *Manager) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { + if adviser == nil { + m.knowledgeAdvisor.Store(nil) + return + } + m.knowledgeAdvisor.Store(&knowledgeAdvisor{ + adviser: adviser, + now: time.Now, + agents: make(map[string]*knowledgeKickState), + }) +} + +// adviseKnowledge is the poll-tick entry point. scrollback is the capture the +// poller already holds; visible is the visible pane, captured once per tick +// and shared with the CI-poll guard. +func (m *Manager) adviseKnowledge(agent *AgentProcess, scrollback, visible string) { + ka := m.knowledgeAdvisor.Load() + if ka == nil || agent == nil || agent.kickDelivering.Load() || agent.LastKick == nil { + return + } + policy := ka.adviser.Policy(agent.Name) + if !policy.Enabled { + return + } + advice, ok := ka.collect(agent.Name, *agent.LastKick, scrollback, visible, policy) + if !ok { + return + } + if m.tmuxSessionHasAttachedClientForAgent(agent) { + return + } + line := renderKnowledgeAdvice(advice) + ka.markDelivered(agent.Name, advice.Slug) + m.logger.Info("knowledge advisor: delivered", + "agent", agent.Name, "slug", advice.Slug, "title", advice.Title) + m.recordPrompt(agent.Name, knowledgeAdvisorTrigger, line) + m.tmuxSendLiteralForAgent(agent, line) + time.Sleep(textToEnterDelay) + m.tmuxSendEntersForAgent(agent) +} + +// collect folds this tick's scrollback into the agent's kick state, asks the +// adviser for every scope that is new since the baseline, and returns the +// next deliverable advice when the cap, cooldown and pane gates all allow it. +func (ka *knowledgeAdvisor) collect(name string, kickAt time.Time, scrollback, visible string, policy crux.KnowledgeAdvisorPolicy) (crux.KnowledgeAdvice, bool) { + scopes := observedKnowledgeScopes(scrollback) + + ka.mu.Lock() + st := ka.agents[name] + if st == nil || !st.kickAt.Equal(kickAt) { + st = &knowledgeKickState{kickAt: kickAt, seen: map[string]bool{}, delivered: map[string]bool{}} + ka.agents[name] = st + } + if !st.baselined { + // Scrollback keeps work from before this kick; what is already on + // screen at the first post-kick poll was not entered during it. + st.baselined = true + for _, sc := range scopes { + st.seen[sc.Key] = true + } + ka.mu.Unlock() + return crux.KnowledgeAdvice{}, false + } + var fresh []crux.KnowledgeScope + for _, sc := range scopes { + if !st.seen[sc.Key] { + st.seen[sc.Key] = true + fresh = append(fresh, sc) + } + } + maxPerKick := policy.MaxPerKick + if maxPerKick <= 0 { + maxPerKick = knowledgeAdvisorDefaultMaxPerKick + } + capped := st.count >= maxPerKick + ka.mu.Unlock() + + if capped { + return crux.KnowledgeAdvice{}, false + } + // The adviser runs outside the lock: it searches the knowledge store. + var found []crux.KnowledgeAdvice + for _, sc := range fresh { + found = append(found, ka.adviser.Advise(name, sc)...) + } + + ka.mu.Lock() + defer ka.mu.Unlock() + for _, adv := range found { + if adv.Slug == "" || st.delivered[adv.Slug] || knowledgeAdvicePending(st.pending, adv.Slug) { + continue + } + st.pending = append(st.pending, adv) + } + if len(st.pending) == 0 { + return crux.KnowledgeAdvice{}, false + } + if knowledgeTurnIdle(visible) { + // The turn the advice was for is over; the next kick primes afresh. + st.pending = nil + return crux.KnowledgeAdvice{}, false + } + if knowledgeToolInFlight(visible) { + return crux.KnowledgeAdvice{}, false + } + cooldown := policy.Cooldown + if cooldown <= 0 { + cooldown = knowledgeAdvisorDefaultCooldown + } + if !st.lastAt.IsZero() && ka.now().Sub(st.lastAt) < cooldown { + return crux.KnowledgeAdvice{}, false + } + next := st.pending[0] + st.pending = st.pending[1:] + return next, true +} + +// markDelivered records a typed slug against the agent's current kick. +func (ka *knowledgeAdvisor) markDelivered(name, slug string) { + ka.mu.Lock() + defer ka.mu.Unlock() + st := ka.agents[name] + if st == nil { + return + } + st.delivered[slug] = true + st.count++ + st.lastAt = ka.now() +} + +func knowledgeAdvicePending(pending []crux.KnowledgeAdvice, slug string) bool { + for _, p := range pending { + if p.Slug == slug { + return true + } + } + return false +} + +// knowledgeTurnIdle reports whether the agent is parked at an empty prompt +// with no work in flight — the turn is over. +func knowledgeTurnIdle(visible string) bool { + return !paneShowsActiveWork(visible) && paneShowsEmptyInputPrompt(visible) +} + +// knowledgeToolInFlight reports whether a tool call is executing right now. +func knowledgeToolInFlight(visible string) bool { + return knowledgeToolInFlightRe.MatchString(visible) +} + +// observedKnowledgeScopes extracts the scopes a pane capture shows the agent +// working in, in first-seen order, one entry per key. +func observedKnowledgeScopes(pane string) []crux.KnowledgeScope { + pane = stripExplainLines(pane) + var out []crux.KnowledgeScope + seen := map[string]bool{} + add := func(sc crux.KnowledgeScope) { + if sc.Key == "" || seen[sc.Key] { + return + } + seen[sc.Key] = true + out = append(out, sc) + } + for _, match := range knowledgePathRe.FindAllStringSubmatch(pane, -1) { + add(knowledgePathScope(match[1])) + } + for _, match := range knowledgeGHRe.FindAllStringSubmatch(pane, -1) { + add(crux.KnowledgeScope{ + Kind: knowledgeAdvisorKindGH, + Key: "gh:" + match[1], + Keywords: knowledgeGHKeywords[match[1]], + }) + } + return out +} + +// knowledgePathScope turns one observed relative path into its scope, or a +// zero scope for root-level files and tooling directories. +func knowledgePathScope(path string) crux.KnowledgeScope { + path = strings.TrimPrefix(path, "./") + segments := strings.Split(path, "/") + dirs := segments[:len(segments)-1] + if len(dirs) == 0 || knowledgeIgnoredDirs[dirs[0]] { + return crux.KnowledgeScope{} + } + for _, d := range dirs { + if d == "" || d == "." || d == ".." { + return crux.KnowledgeScope{} + } + } + if len(dirs) > knowledgeAdvisorMaxScopeDepth { + dirs = dirs[:knowledgeAdvisorMaxScopeDepth] + } + var keywords []string + for _, d := range dirs { + if !knowledgeGenericSegments[strings.ToLower(d)] { + keywords = append(keywords, d) + } + } + return crux.KnowledgeScope{ + Kind: knowledgeAdvisorKindPath, + Key: strings.Join(dirs, "/"), + Path: path, + Keywords: keywords, + } +} + +// renderKnowledgeAdvice is the single line typed into the session. +func renderKnowledgeAdvice(adv crux.KnowledgeAdvice) string { + var b strings.Builder + b.WriteString("📚 Knowledge: ") + b.WriteString(oneLine(adv.Title)) + if summary := headRunes(oneLine(adv.Summary), knowledgeAdvisorMaxSummary); summary != "" { + b.WriteString(" — ") + b.WriteString(summary) + } + if ref := strings.TrimSpace(adv.Ref); ref != "" { + b.WriteString(" (full: ") + b.WriteString(ref) + b.WriteString(")") + } + return b.String() +} + +// headRunes keeps s within n runes, ellipsis included, so the typed line's +// body never exceeds the documented cap. +func headRunes(s string, n int) string { + r := []rune(s) + if len(r) <= n { + return s + } + return strings.TrimSpace(string(r[:n-1])) + "…" +} diff --git a/src/crux/agent/knowledge_advisor_test.go b/src/crux/agent/knowledge_advisor_test.go new file mode 100644 index 0000000000..110968f430 --- /dev/null +++ b/src/crux/agent/knowledge_advisor_test.go @@ -0,0 +1,322 @@ +package agent + +import ( + "reflect" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/config" +) + +// knowledge_advisor_test.go covers the mid-task knowledge advisor (#17052): +// the pure pieces (scope extraction, the typed line, the pane gates) as tables, +// and the per-kick delivery loop against a fake adviser, a fake clock and the +// funcTerminal seams — no tmux, no time.Sleep beyond the package TestMain's +// shrunk textToEnterDelay. + +// fakeAdviser answers Advise from a fixed table and records every scope asked. +type fakeAdviser struct { + policy crux.KnowledgeAdvisorPolicy + byKey map[string][]crux.KnowledgeAdvice + asked []string +} + +func (f *fakeAdviser) Policy(string) crux.KnowledgeAdvisorPolicy { return f.policy } + +func (f *fakeAdviser) Advise(_ string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + f.asked = append(f.asked, scope.Key) + return f.byKey[scope.Key] +} + +// workingPane is a Claude Code pane mid-turn: a tool just finished and the +// model is generating, so the busy footer is up and no tool is in flight. +const workingPane = "⏺ Read(src/crux/agent/manager.go)\n⎿ Read 120 lines\n\n✶ Thinking… (4s · ↓ 94 tokens)\n\n❯ \n esc to interrupt" + +// toolPane is the same pane while a shell command runs. +const toolPane = "⏺ Running 1 shell command…\n\n❯ \n esc to interrupt" + +// idlePane is a finished turn: empty prompt, no busy footer. +const idlePane = "✻ Worked for 26s\n\n❯ " + +func advisorManager(t *testing.T, adviser crux.KnowledgeAdviser) (*Manager, *AgentProcess, *[]string) { + t.Helper() + m := testManager(4) + kickAt := time.Date(2026, 11, 7, 12, 0, 0, 0, time.UTC) + a := &AgentProcess{ + Name: "developer", + Config: config.AgentConfig{Backend: "claude"}, + tmuxSession: "hive-developer-test-nonexistent", + LastKick: &kickAt, + } + m.agents[a.Name] = a + var typed []string + termSeams(m).sessionAttached = func(*AgentProcess) bool { return false } + termSeams(m).sendLiteral = func(_ *AgentProcess, text string) { typed = append(typed, text) } + termSeams(m).sendKeys = func(*AgentProcess, ...string) {} + m.SetKnowledgeAdviser(adviser) + return m, a, &typed +} + +// fakeClock replaces the advisor's clock; tests advance it by hand. +func fakeClock(m *Manager, start time.Time) *time.Time { + now := start + m.knowledgeAdvisor.Load().now = func() time.Time { return now } + return &now +} + +func enabledPolicy() crux.KnowledgeAdvisorPolicy { + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: 2, Cooldown: time.Minute} +} + +func TestObservedKnowledgeScopes(t *testing.T) { + tests := []struct { + name string + pane string + want []string + }{ + { + name: "claude code expanded tool calls", + pane: "⏺ Read(src/crux/agent/manager.go)\n⏺ Update(src/pkg/config/config.go)", + want: []string{"src/crux/agent", "src/pkg/config"}, + }, + { + name: "copilot cli and shell shapes, deeper paths truncate to three segments", + pane: "● Edit src/pkg/dashboard/static/app.js\n$ cat ./src/docs/operator-reference.md", + want: []string{"src/pkg/dashboard", "src/docs"}, + }, + { + name: "one key per scope, first-seen order", + pane: "src/crux/agent/a.go src/crux/agent/b.go .github/workflows/ci.yml", + want: []string{"src/crux/agent", ".github/workflows"}, + }, + { + name: "gh families", + pane: "$ gh pr checks 17052\n$ gh run view 12 --log-failed\n$ gh pr view 1", + want: []string{"gh:pr", "gh:run"}, + }, + { + name: "root files, urls, absolute paths and tooling dirs are not scopes", + pane: "README.md https://github.com/hivecommons/hive/blob/v5/src/x.go /tmp/out.log node_modules/ws/index.js vendor/x/y.go", + want: nil, + }, + { + name: "explain narration is not work", + pane: config.ExplainLinePrefix + " reading src/crux/agent/manager.go next", + want: nil, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var got []string + for _, sc := range observedKnowledgeScopes(tt.pane) { + got = append(got, sc.Key) + } + if !reflect.DeepEqual(got, tt.want) { + t.Errorf("scopes = %v, want %v", got, tt.want) + } + }) + } +} + +func TestKnowledgePathScopeKeywordsDropGenericSegments(t *testing.T) { + sc := knowledgePathScope("./src/crux/agent/manager_kick.go") + if sc.Kind != knowledgeAdvisorKindPath || sc.Key != "src/crux/agent" || sc.Path != "src/crux/agent/manager_kick.go" { + t.Fatalf("scope = %+v", sc) + } + if want := []string{"crux", "agent"}; !reflect.DeepEqual(sc.Keywords, want) { + t.Errorf("keywords = %v, want %v", sc.Keywords, want) + } + if gh := observedKnowledgeScopes("gh pr list")[0]; !reflect.DeepEqual(gh.Keywords, []string{"pull request", "pr"}) { + t.Errorf("gh keywords = %v", gh.Keywords) + } +} + +func TestRenderKnowledgeAdvice(t *testing.T) { + long := strings.Repeat("word ", 100) + line := renderKnowledgeAdvice(crux.KnowledgeAdvice{ + Slug: "scripts-tree", Title: "Re-pin TRUSTED_SCRIPTS_TREE", Summary: "line one\nline two " + long, Ref: "knowledge entry scripts-tree", + }) + if !strings.HasPrefix(line, "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — line one line two word") { + t.Errorf("line = %q", line) + } + if !strings.HasSuffix(line, " (full: knowledge entry scripts-tree)") { + t.Errorf("line = %q", line) + } + if strings.Contains(line, "\n") { + t.Error("line must be a single line") + } + body := strings.TrimSuffix(strings.TrimPrefix(line, "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — "), " (full: knowledge entry scripts-tree)") + if n := len([]rune(body)); n > knowledgeAdvisorMaxSummary { + t.Errorf("summary is %d runes, cap %d", n, knowledgeAdvisorMaxSummary) + } + if got := renderKnowledgeAdvice(crux.KnowledgeAdvice{Title: "T"}); got != "📚 Knowledge: T" { + t.Errorf("bare title = %q", got) + } +} + +func TestKnowledgePaneGates(t *testing.T) { + tests := []struct { + name string + pane string + idle, inTool bool + }{ + {"generating", workingPane, false, false}, + {"shell command running", toolPane, false, true}, + {"omp tool call", "⏺ Running… (esc to cancel)", false, true}, + {"turn over", idlePane, true, false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := knowledgeTurnIdle(tt.pane); got != tt.idle { + t.Errorf("idle = %v, want %v", got, tt.idle) + } + if got := knowledgeToolInFlight(tt.pane); got != tt.inTool { + t.Errorf("toolInFlight = %v, want %v", got, tt.inTool) + } + }) + } +} + +func TestAdviseKnowledge_BaselineThenNewScopeDelivers(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), 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."}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + + // First tick after the kick: src/scripts is already in scrollback from + // before the kick, so it is baseline, not a new scope. + m.adviseKnowledge(a, "⏺ Read(src/scripts/old.sh)", workingPane) + if len(adv.asked) != 0 || len(*typed) != 0 { + t.Fatalf("baseline tick asked %v, typed %v", adv.asked, *typed) + } + m.adviseKnowledge(a, "⏺ Read(src/scripts/old.sh)", workingPane) + if len(adv.asked) != 0 { + t.Fatalf("baseline scope re-asked: %v", adv.asked) + } + + // A new kick resets the baseline, so the same scope is new again. + later := a.LastKick.Add(time.Hour) + a.LastKick = &later + m.adviseKnowledge(a, "⏺ Read(src/crux/agent/x.go)", workingPane) + m.adviseKnowledge(a, "⏺ Read(src/crux/agent/x.go)\n⏺ Edit(src/scripts/ci.sh)", workingPane) + if !reflect.DeepEqual(adv.asked, []string{"src/scripts"}) { + t.Fatalf("asked = %v", adv.asked) + } + if len(*typed) != 1 || !strings.HasPrefix((*typed)[0], "📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — Any src/scripts edit") { + t.Fatalf("typed = %v", *typed) + } + // Same slug never twice in a kick, even if another scope matches it. + adv.byKey["gh:pr"] = adv.byKey["src/scripts"] + m.adviseKnowledge(a, "⏺ Edit(src/scripts/ci.sh)\n$ gh pr checks 1", workingPane) + if len(*typed) != 1 { + t.Fatalf("duplicate slug typed: %v", *typed) + } +} + +func TestAdviseKnowledge_CapCooldownAndPaneGates(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}, {Slug: "a2", Title: "A2"}, {Slug: "a3", Title: "A3"}}, + }} + m, a, typed := advisorManager(t, adv) + now := fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) // baseline + + // Tool in flight: the advice queues, nothing is typed. + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", toolPane) + if len(*typed) != 0 { + t.Fatalf("typed during a tool call: %v", *typed) + } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 1 || (*typed)[0] != "📚 Knowledge: A1" { + t.Fatalf("typed = %v", *typed) + } + // Cooldown holds the second line back until the clock moves. + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 1 { + t.Fatalf("cooldown ignored: %v", *typed) + } + *now = now.Add(time.Minute) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 2 || (*typed)[1] != "📚 Knowledge: A2" { + t.Fatalf("typed = %v", *typed) + } + // MaxPerKick is 2: the third candidate never goes out this kick. + *now = now.Add(time.Minute) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 2 { + t.Fatalf("cap ignored: %v", *typed) + } + if len(adv.asked) != 1 { + t.Errorf("adviser asked %d times for one scope, want 1", len(adv.asked)) + } +} + +func TestAdviseKnowledge_IdleTurnDropsPending(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", toolPane) // queued + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", idlePane) // turn over: dropped + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatalf("advice for a finished turn was typed: %v", *typed) + } +} + +func TestAdviseKnowledge_Refusals(t *testing.T) { + newCase := func() (*fakeAdviser, *Manager, *AgentProcess, *[]string) { + adv := &fakeAdviser{policy: enabledPolicy(), byKey: map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}}, + }} + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + return adv, m, a, typed + } + t.Run("disabled policy parses nothing", func(t *testing.T) { + adv, m, a, typed := newCase() + adv.policy = crux.KnowledgeAdvisorPolicy{} + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(adv.asked) != 0 || len(*typed) != 0 { + t.Fatalf("asked %v typed %v", adv.asked, *typed) + } + }) + t.Run("kick being typed", func(t *testing.T) { + _, m, a, typed := newCase() + a.kickDelivering.Store(true) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed into a kick in delivery") + } + }) + t.Run("no kick yet", func(t *testing.T) { + _, m, a, typed := newCase() + a.LastKick = nil + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed before any kick") + } + }) + t.Run("human attached", func(t *testing.T) { + _, m, a, typed := newCase() + termSeams(m).sessionAttached = func(*AgentProcess) bool { return true } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed over an attached client") + } + }) + t.Run("no adviser installed", func(t *testing.T) { + _, m, a, typed := newCase() + m.SetKnowledgeAdviser(nil) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatal("typed with the advisor off") + } + }) +} diff --git a/src/crux/agent/manager.go b/src/crux/agent/manager.go index 6110fdf159..f5d5043405 100644 --- a/src/crux/agent/manager.go +++ b/src/crux/agent/manager.go @@ -723,13 +723,13 @@ type Manager struct { breakerPaused map[string]bool // recordPromptCallback, when set, persists the fully-expanded prompt text - // delivered to an agent so owners can review it later. - // - // Held as an atomic.Pointer rather than behind m.mu because the kick path + // delivered to an agent so owners can review it later. Held as an + // atomic.Pointer rather than behind m.mu because the kick path // (deliverKickLocked) already holds m.mu when it fires this. m.mu is a // non-reentrant RWMutex, so reading the callback under a second Lock there // would deadlock the kick path. recordPromptCallback atomic.Pointer[func(agent, trigger, prompt string)] + knowledgeAdvisor atomic.Pointer[knowledgeAdvisor] // mid-task knowledge advisor (#17052); nil = off // spanStarter, when set, opens the trace spans the runtime emits // (SendKick's agent.send_kick). Same atomic.Pointer discipline as // recordPromptCallback: read on paths that hold m.mu. Nil falls back to diff --git a/src/crux/agent/manager_poll.go b/src/crux/agent/manager_poll.go index 31bd3da5fb..112f75cad4 100644 --- a/src/crux/agent/manager_poll.go +++ b/src/crux/agent/manager_poll.go @@ -325,7 +325,9 @@ func (m *Manager) pollTmuxOutputForAgent(agent *AgentProcess, ctx context.Contex } if !IsInferenceBackend(effectiveBackend(agent)) { - m.nudgeIfPollingCI(agent, output, m.captureVisiblePaneForAgent(agent)) + visible := m.captureVisiblePaneForAgent(agent) + m.nudgeIfPollingCI(agent, output, visible) + m.adviseKnowledge(agent, output, visible) } // Detect copilot hung: if running long enough with no CLI prompt, diff --git a/src/crux/api/client/client_test.go b/src/crux/api/client/client_test.go index fde565154b..3e2b2443a4 100644 --- a/src/crux/api/client/client_test.go +++ b/src/crux/api/client/client_test.go @@ -139,8 +139,10 @@ func TestParityHostVersusSetterTable(t *testing.T) { t.Errorf("api.HostSetters[%q] has unknown kind %q", name, row.Kind) } } - if api.HostSetters["SetSpanStarter"].Kind != api.HostSetterInProcessOnly { - t.Error("SetSpanStarter is the one in-process-only setter") + for _, name := range []string{"SetSpanStarter", "SetKnowledgeAdviser"} { + if api.HostSetters[name].Kind != api.HostSetterInProcessOnly { + t.Errorf("%s is an in-process-only setter", name) + } } } diff --git a/src/crux/api/runtime.go b/src/crux/api/runtime.go index df7f27f1ae..a9e59524b9 100644 --- a/src/crux/api/runtime.go +++ b/src/crux/api/runtime.go @@ -825,7 +825,7 @@ var HostSetters = map[string]HostSetter{ "SetSandboxAuditCallback": {HostSetterEvent, EventSandboxAudit}, "SetAuditSink": {HostSetterEvent, EventAudit}, "SetConditionReporter": {HostSetterEvent, EventCondition + ", " + hostViaConditions}, - // In-process only. - "SetSpanStarter": {HostSetterInProcessOnly, "OpenTelemetry global tracer in the runtime process; trajectory events are independent of spans"}, + "SetSpanStarter": {HostSetterInProcessOnly, "OpenTelemetry global tracer in the runtime process; trajectory events are independent of spans"}, + "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/cruxtest/recorder_knowledge.go b/src/crux/cruxtest/recorder_knowledge.go new file mode 100644 index 0000000000..01ed6d9085 --- /dev/null +++ b/src/crux/cruxtest/recorder_knowledge.go @@ -0,0 +1,10 @@ +package cruxtest + +import "github.com/hivecommons/hive/crux" + +// SetKnowledgeAdviser records the mid-task knowledge advisor seam +// (hivecommons/hive#17052); it lives apart from recorder.go only because that +// file sits at its size-ratchet baseline. +func (r *Recorder) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { + r.record("SetKnowledgeAdviser", adviser != nil) +} diff --git a/src/crux/host_wiring.go b/src/crux/host_wiring.go index 501bc37de7..f87cc17c7a 100644 --- a/src/crux/host_wiring.go +++ b/src/crux/host_wiring.go @@ -58,4 +58,9 @@ type Host interface { SetAuditSink(sink AuditSink) SetConditionReporter(r ConditionReporter) SetSpanStarter(fn SpanStarter) + // SetKnowledgeAdviser installs the hive-side matcher the mid-task + // knowledge advisor asks when an agent's work enters a new scope + // (hivecommons/hive#17052). In-process-only in phase 1: the knowledge + // store lives in the hive process and the adviser is a Go call into it. + SetKnowledgeAdviser(adviser KnowledgeAdviser) } diff --git a/src/crux/knowledge_advice.go b/src/crux/knowledge_advice.go new file mode 100644 index 0000000000..a7b5aa3882 --- /dev/null +++ b/src/crux/knowledge_advice.go @@ -0,0 +1,59 @@ +package crux + +import "time" + +// KnowledgeScope is one unit of work context the runtime observed an agent +// enter after its kick (hivecommons/hive#17052): a source directory it read +// or edited, or a GitHub CLI family it started using. Key is stable per +// scope and is what the runtime dedupes on within a kick. +type KnowledgeScope struct { + // Kind is "path" or "gh". + Kind string + // Key is the dedupe key: "src/crux/agent" for a path scope, "gh:pr" for + // a gh family. + Key string + // Path is the relative file path that opened a path scope; "" for gh. + Path string + // Keywords are the search terms the scope contributes to the matcher. + Keywords []string +} + +// KnowledgeAdvice is one knowledge entry the adviser matched to a scope. +// The runtime renders it as a single line typed into the live session. +type KnowledgeAdvice struct { + // Slug identifies the entry; the runtime never delivers a slug twice in + // one kick. + Slug string + // Title is the entry title. + Title string + // Summary is the body, already collapsed to one line and capped by the + // adviser. + Summary string + // Ref tells the agent where the full entry is: a source URL or the + // knowledge entry id. + Ref string +} + +// KnowledgeAdvisorPolicy is the delivery policy for one agent, resolved per +// call off the live hive config so a dashboard change applies without a +// restart. +type KnowledgeAdvisorPolicy struct { + // Enabled false means the runtime neither parses the agent's pane for + // scopes nor types anything. + Enabled bool + // MaxPerKick caps deliveries per kick; non-positive means the default. + MaxPerKick int + // Cooldown is the minimum gap between two deliveries to one agent; + // non-positive means the default. + Cooldown time.Duration +} + +// KnowledgeAdviser is the hive side of the mid-task knowledge advisor. +type KnowledgeAdviser interface { + // Policy returns the delivery policy for agent. + Policy(agent string) KnowledgeAdvisorPolicy + // Advise returns the entries worth surfacing to agent for a scope it has + // just entered, excluding anything its kick already carried. Order is + // best first. It runs on the agent's poll goroutine and must be bounded. + Advise(agent string, scope KnowledgeScope) []KnowledgeAdvice +} diff --git a/src/docs/design/crux.md b/src/docs/design/crux.md index f616d7477c..e51a7df08b 100644 --- a/src/docs/design/crux.md +++ b/src/docs/design/crux.md @@ -708,6 +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` on the poll tick 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 | 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 diff --git a/src/docs/knowledge-curator.md b/src/docs/knowledge-curator.md index 053f812fa2..5eb823b5d3 100644 --- a/src/docs/knowledge-curator.md +++ b/src/docs/knowledge-curator.md @@ -638,6 +638,54 @@ knowledge: repos: [hivecommons/hive] ``` +## Mid-task knowledge advisor (`knowledge.advisor`) + +The kick primer above runs once, when the kick is typed. The advisor +(hivecommons/hive#17052) keeps watching after that: every poll tick it +reads the scopes the agent's pane shows it working in — a directory prefix +such as `src/crux/agent` from a `Read(...)`/`Edit ...` line, or a `gh pr` / +`gh issue` / `gh run` command family — and the first time a scope appears +that was not on screen when the kick landed, it asks the same `Primer` +(under the same `knowledge.agent_scopes` restriction) for entries about it. +Each hit is typed into the live session as one line, like a CI-poll nudge: + +``` +📚 Knowledge: Re-pin TRUSTED_SCRIPTS_TREE — Any src/scripts edit must … (full: https://…) +``` + +Rules, all enforced by the runtime (`crux/agent/knowledge_advisor.go`): + +- **Off by default.** `knowledge.advisor: true` turns it on; `knowledge.enabled` + must also be on. Flip it once your own hive has run it for a while. +- **At most `knowledge.advisor_max_per_kick` lines per kick** (default 3), + with a two-minute cooldown between lines. +- **Never an entry the kick already carried.** The primer records which + entries survived the byte cap; those are excluded, and a slug is typed at + most once per kick. +- **Never into a tool call, never after the turn.** A line waits while a + shell command or tool is running; if the agent reaches an empty prompt + first, the pending advice is dropped (the next kick primes afresh). It is + also skipped while a human is attached to the pane and while a kick is + being typed. +- **Per-agent opt-out:** `knowledge.advisor_exclude_agents: [scanner]` + matches an agent name or its replica family base name. +- **Measurable.** Each delivery is recorded in the dashboard prompt history + with trigger `knowledge-advisor` and logged as + `knowledge advisor: delivered` with the agent and slug. + +```yaml +knowledge: + enabled: true + advisor: true + advisor_max_per_kick: 3 + advisor_exclude_agents: [scanner] +``` + +Phase 1 is a pure matcher with no model in the loop; the LLM-ranked variant +(OMP's advisor agent as the model) is hivecommons/hive#17054. The advisor is +wired only when the agent runtime runs in-process; the `crux serve` sidecar +has no adviser in this phase. + ## Open questions - #4944 (the issue behind this section) suggested documenting auth for diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index cdac8c2382..3e736ecef9 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -299,6 +299,7 @@ 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). | | `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/pkg/config/config.go b/src/pkg/config/config.go index 85a446d85d..91fd6d6374 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -6661,6 +6661,9 @@ func (c *Config) applyDefaults() { if c.Knowledge.Primer.MaxBytes == 0 { c.Knowledge.Primer.MaxBytes = defaultKnowledgeMaxBytes } + if c.Knowledge.AdvisorMaxPerKick == 0 { + c.Knowledge.AdvisorMaxPerKick = DefaultKnowledgeAdvisorMaxPerKick + } if c.Knowledge.Primer.MergeStrategy == "" { c.Knowledge.Primer.MergeStrategy = DefaultKnowledgePrimerMergeStrategy } diff --git a/src/pkg/config/knowledge_advisor_test.go b/src/pkg/config/knowledge_advisor_test.go new file mode 100644 index 0000000000..a5e06bf2f9 --- /dev/null +++ b/src/pkg/config/knowledge_advisor_test.go @@ -0,0 +1,75 @@ +package config + +import ( + "testing" + + "gopkg.in/yaml.v3" +) + +// Mid-task knowledge advisor keys (hivecommons/hive#17052): off unless +// knowledge.advisor is set, with per-agent and per-family opt-out. + +func TestKnowledgeAdvisorEnabledFor(t *testing.T) { + base := func() *Config { + return &Config{ + AgentRuntimeConfig: AgentRuntimeConfig{Agents: map[string]AgentConfig{ + "developer": {Backend: "claude"}, + "developer-2": {Backend: "claude", ReplicaOf: "developer"}, + "scanner": {Backend: "claude"}, + }}, + Knowledge: KnowledgeConfig{Enabled: true, Advisor: true}, + } + } + tests := []struct { + name string + mut func(*Config) + agent string + want bool + }{ + {"on", func(*Config) {}, "developer", true}, + {"default off", func(c *Config) { c.Knowledge.Advisor = false }, "developer", false}, + {"knowledge off", func(c *Config) { c.Knowledge.Enabled = false }, "developer", false}, + {"excluded by name", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{" scanner "} }, "scanner", false}, + {"excluded by family", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{"developer"} }, "developer-2", false}, + {"other agent unaffected", func(c *Config) { c.Knowledge.AdvisorExcludeAgents = []string{"scanner"} }, "developer", true}, + {"empty agent", func(*Config) {}, "", false}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + c := base() + tt.mut(c) + if got := c.KnowledgeAdvisorEnabledFor(tt.agent); got != tt.want { + t.Errorf("KnowledgeAdvisorEnabledFor(%q) = %v, want %v", tt.agent, got, tt.want) + } + }) + } + var nilCfg *Config + if nilCfg.KnowledgeAdvisorEnabledFor("developer") { + t.Error("nil config enabled the advisor") + } +} + +func TestKnowledgeAdvisor_ParseAndDefault(t *testing.T) { + var k KnowledgeConfig + err := yaml.Unmarshal([]byte("advisor: true\nadvisor_max_per_kick: 5\nadvisor_exclude_agents: [scanner]\n"), &k) + if err != nil { + t.Fatal(err) + } + if !k.Advisor || k.AdvisorMaxPerKick != 5 || len(k.AdvisorExcludeAgents) != 1 { + t.Fatalf("parsed %+v", k) + } + + 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}, + } + cfg.applyDefaults() + if cfg.Knowledge.Advisor { + t.Error("advisor must default off") + } + if cfg.Knowledge.AdvisorMaxPerKick != DefaultKnowledgeAdvisorMaxPerKick { + t.Errorf("advisor_max_per_kick = %d, want %d", cfg.Knowledge.AdvisorMaxPerKick, DefaultKnowledgeAdvisorMaxPerKick) + } +} diff --git a/src/pkg/config/knowledge_config.go b/src/pkg/config/knowledge_config.go index 63ab56386e..34597e07c5 100644 --- a/src/pkg/config/knowledge_config.go +++ b/src/pkg/config/knowledge_config.go @@ -44,6 +44,18 @@ type KnowledgeConfig struct { // kick primer and through agent-identified TOC/entry reads. A missing // entry or an empty field is unrestricted. AgentScopes map[string]KnowledgeAgentScope `yaml:"agent_scopes,omitempty"` + // Advisor turns on the mid-task knowledge advisor (hivecommons/hive#17052): + // when a running agent's pane first shows a source directory or `gh` + // command family its kick did not know about, matching entries are typed + // into the live session as one-line hints. Off by default while hive's + // own hive dogfoods it. + Advisor bool `yaml:"advisor,omitempty"` + // AdvisorMaxPerKick caps advisor deliveries per kick; zero takes + // DefaultKnowledgeAdvisorMaxPerKick. + AdvisorMaxPerKick int `yaml:"advisor_max_per_kick,omitempty"` + // AdvisorExcludeAgents lists agents (by name or family base name) the + // advisor never types at, e.g. lanes whose work is reading, not editing. + AdvisorExcludeAgents []string `yaml:"advisor_exclude_agents,omitempty"` } // PublicKnowledgeConfig is the dashboard-persisted owner override for the @@ -118,6 +130,7 @@ const ( DefaultKnowledgePrimerMaxFacts = 25 DefaultKnowledgePrimerMaxBytes = 4096 DefaultKnowledgePrimerMergeStrategy = "precedence" + DefaultKnowledgeAdvisorMaxPerKick = 3 ) // KnowledgeSchedules are the schedule values the bead synthesizer, curator @@ -353,6 +366,23 @@ func ValidateKnowledgeAgentScopes(scopes map[string]KnowledgeAgentScope) error { // KnowledgeAgentScope returns the knowledge scope bound to agent. A replica // without its own entry inherits its base agent's scope. ok is false when the // agent is unrestricted. +// KnowledgeAdvisorEnabledFor reports whether the mid-task knowledge advisor +// may type at agent: knowledge and the advisor are on, and neither the agent +// nor its family base name is in knowledge.advisor_exclude_agents. +func (c *Config) KnowledgeAdvisorEnabledFor(agent string) bool { + if c == nil || !c.Knowledge.Enabled || !c.Knowledge.Advisor || agent == "" { + return false + } + base := c.BaseAgentName(agent) + for _, name := range c.Knowledge.AdvisorExcludeAgents { + name = strings.TrimSpace(name) + if name != "" && (name == agent || name == base) { + return false + } + } + return true +} + 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 80962ac227..5d4bbf6375 100644 --- a/src/pkg/config/testdata/agent_runtime_golden.json +++ b/src/pkg/config/testdata/agent_runtime_golden.json @@ -547,7 +547,10 @@ "MaxBytes": 0, "Repos": null }, - "AgentScopes": null + "AgentScopes": null, + "Advisor": false, + "AdvisorMaxPerKick": 0, + "AdvisorExcludeAgents": null }, "Hub": { "Enabled": false, diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index bc41381782..0b7861954b 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -344,6 +344,9 @@ issues.rfc_existing_check.max_age # triage existing-coverage check; yaml-only (# issues.rfc_existing_check.max_matches # triage existing-coverage check; yaml-only (#13575) issues.rfc_existing_check.post_when_nothing_found # triage existing-coverage check; yaml-only (#13575) issues.sha_hold_trusted_label # TODO #11854 +knowledge.advisor # mid-task knowledge advisor, yaml-only while it soaks (#17052) +knowledge.advisor_exclude_agents[] # mid-task knowledge advisor, yaml-only while it soaks (#17052) +knowledge.advisor_max_per_kick # mid-task knowledge advisor, yaml-only while it soaks (#17052) knowledge.agent_scopes..include_states[] # TODO #11854 knowledge.agent_scopes..layers[] # TODO #11854 knowledge.agent_scopes..repos[] # TODO #11854 diff --git a/src/pkg/knowledge/primer_render.go b/src/pkg/knowledge/primer_render.go index 6175681214..27740fdee3 100644 --- a/src/pkg/knowledge/primer_render.go +++ b/src/pkg/knowledge/primer_render.go @@ -72,6 +72,7 @@ func primerMaxBytes(n int) int { // reader of the kick knows the primer was bounded rather than exhaustive. func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) { var omitted PrimerOmitted + pk.rendered = nil if len(pk.Facts) == 0 { return "", omitted } @@ -109,6 +110,7 @@ func (pk *PrimedKnowledge) Render() (string, PrimerOmitted) { headingWritten = true } b.WriteString(entry) + pk.rendered = append(pk.rendered, f.Slug) remaining -= need } } diff --git a/src/pkg/knowledge/primer_rendered_slugs_test.go b/src/pkg/knowledge/primer_rendered_slugs_test.go new file mode 100644 index 0000000000..9d3eaefb9f --- /dev/null +++ b/src/pkg/knowledge/primer_rendered_slugs_test.go @@ -0,0 +1,40 @@ +package knowledge + +import ( + "reflect" + "testing" +) + +// RenderedSlugs (hivecommons/hive#17052) tells the mid-task advisor which +// entries the kick really carried, so it never re-sends a capped-out one and +// never counts a capped-out one as already delivered. + +func TestPrimerRenderedSlugs_TracksKeptFactsOnly(t *testing.T) { + pk := &PrimedKnowledge{Facts: renderFacts(20, 280), MaxBytes: 2048} + if pk.RenderedSlugs() != nil { + t.Fatal("slugs before Render should be nil") + } + _, omitted := pk.Render() + got := pk.RenderedSlugs() + if len(got)+omitted.Facts != len(pk.Facts) || len(got) == 0 { + t.Fatalf("rendered %d + omitted %d != %d", len(got), omitted.Facts, len(pk.Facts)) + } + var want []string + for _, f := range pk.Facts[:len(got)] { + want = append(want, f.Slug) + } + if !reflect.DeepEqual(got, want) { + t.Errorf("slugs = %v, want %v", got, want) + } + got[0] = "mutated" + if pk.RenderedSlugs()[0] == "mutated" { + t.Error("RenderedSlugs must return a copy") + } + + // A second Render starts the list over instead of appending. + pk.MaxBytes = 1 << 20 + pk.Render() + if n := len(pk.RenderedSlugs()); n != len(pk.Facts) { + t.Errorf("uncapped re-render kept %d slugs, want %d", n, len(pk.Facts)) + } +} diff --git a/src/pkg/knowledge/types.go b/src/pkg/knowledge/types.go index 7831b12368..d704ccfd9e 100644 --- a/src/pkg/knowledge/types.go +++ b/src/pkg/knowledge/types.go @@ -307,6 +307,15 @@ type PrimedKnowledge struct { // MaxBytes bounds the rendered prompt text (PrimerConfig.MaxBytes). Zero // means DefaultPrimerMaxBytes. MaxBytes int `json:"-"` + // rendered is the slugs Render kept, in render order, for the mid-task + // advisor's "never repeat what the kick carried" rule (#17052). + rendered []string +} + +// RenderedSlugs returns the slugs of the facts the last Render kept — the +// entries the kick actually carried, excluding those the byte cap dropped. +func (pk *PrimedKnowledge) RenderedSlugs() []string { + return append([]string(nil), pk.rendered...) } // FormatForPrompt renders primed facts as markdown for injection into an agent's diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index 126f46a789..b8f4b90ccf 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -305,6 +305,7 @@ func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue) } primed := primer.PrimeScoped(context.Background(), scope, nil, keywords) result, omitted := primed.Render() + s.primedSlugs.Store(agentName, primed.RenderedSlugs()) inj := knowledgeInjection{ Section: result, Bytes: len(result), @@ -359,6 +360,19 @@ func (s *Scheduler) logKnowledgeInjection(agentName string, inj knowledgeInjecti ) } +// KickPrimedSlugs returns the knowledge slugs the most recent kick message +// built for agentName actually rendered in its `# Relevant Knowledge` block. +// The mid-task advisor (#17052) uses it to never repeat what the kick carried; +// facts the byte cap dropped are not in it and so stay eligible. +func (s *Scheduler) KickPrimedSlugs(agentName string) []string { + v, ok := s.primedSlugs.Load(agentName) + if !ok { + return nil + } + slugs, _ := v.([]string) + return slugs +} + // extractKeywords pulls searchable terms from issue labels and titles. // Title words are included because labels alone are often all noise // (triage/accepted, kind/bug) and produce zero keywords after filtering. diff --git a/src/pkg/scheduler/scheduler.go b/src/pkg/scheduler/scheduler.go index b01154702f..a9289fd3e9 100644 --- a/src/pkg/scheduler/scheduler.go +++ b/src/pkg/scheduler/scheduler.go @@ -23,6 +23,7 @@ type Scheduler struct { lastActionable *github.ActionableResult logger *slog.Logger primerCapLogged sync.Map // agent|cap_bytes -> omitted fact count last logged at INFO + primedSlugs sync.Map // agent -> []string slugs the last kick's knowledge block rendered (#17052) promptResolver *promptsrc.Resolver auditFunc AuditFunc advisoryFunc AdvisoryFunc