From b82bc0cf96558d76c351745c3869d276eee288f6 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 7 Nov 2026 21:04:26 -0500 Subject: [PATCH 1/2] =?UTF-8?q?=E2=9C=A8=20crux:=20asynchronous=20Knowledg?= =?UTF-8?q?eAdviser=20with=20scope=20Action=20and=20scrubbed=20PaneTail?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com> --- .../changed-knowledge-adviser-async.md | 1 + src/cmd/hive/knowledge_adviser.go | 8 +- src/crux/agent/knowledge_advisor.go | 317 +++++++++++++++--- src/crux/agent/knowledge_advisor_test.go | 290 ++++++++++++++++ src/crux/knowledge_advice.go | 22 +- src/docs/agent-knowledge-and-memory.md | 9 + src/docs/design/crux.md | 2 +- src/docs/knowledge-curator.md | 20 +- 8 files changed, 617 insertions(+), 52 deletions(-) create mode 100644 changelog.d/changed-knowledge-adviser-async.md diff --git a/changelog.d/changed-knowledge-adviser-async.md b/changelog.d/changed-knowledge-adviser-async.md new file mode 100644 index 0000000000..0fd71c5c32 --- /dev/null +++ b/changelog.d/changed-knowledge-adviser-async.md @@ -0,0 +1 @@ +- **knowledge advisor:** the runtime now calls the knowledge adviser off the agent's poll goroutine with at most one call in flight per agent, so a slow adviser no longer stalls the tick; results are held until the delivery gates pass and dropped if the kick changed. Each observed scope carries an `Action` (`read`/`edit`/`run`) and is re-advised at most once, on its first edit or next `gh` command. An adviser can request a token-scrubbed pane tail, which the built-in matcher never does (#17153). diff --git a/src/cmd/hive/knowledge_adviser.go b/src/cmd/hive/knowledge_adviser.go index c7c2f97d8b..58b357d75f 100644 --- a/src/cmd/hive/knowledge_adviser.go +++ b/src/cmd/hive/knowledge_adviser.go @@ -18,8 +18,9 @@ import ( // 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 bounds one adviser query. The runtime calls it off + // the poll goroutine, one call per agent at a time, so a slow wiki layer + // only holds back that agent's next scope. 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. @@ -61,7 +62,8 @@ func (a *knowledgeAdviser) Policy(agent string) crux.KnowledgeAdvisorPolicy { if cfg == nil || !cfg.KnowledgeAdvisorEnabledFor(agent) { return crux.KnowledgeAdvisorPolicy{} } - return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: cfg.Knowledge.AdvisorMaxPerKick} + // The matcher works from the scope alone; it never asks for pane text. + return crux.KnowledgeAdvisorPolicy{Enabled: true, MaxPerKick: cfg.Knowledge.AdvisorMaxPerKick, WantsPaneTail: false} } // Advise searches the knowledge store for scope. Until #17045 lands the diff --git a/src/crux/agent/knowledge_advisor.go b/src/crux/agent/knowledge_advisor.go index 6cd0896605..5358df223d 100644 --- a/src/crux/agent/knowledge_advisor.go +++ b/src/crux/agent/knowledge_advisor.go @@ -7,6 +7,7 @@ import ( "time" "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/logscrub" ) // Mid-task knowledge advisor (hivecommons/hive#17052). @@ -21,6 +22,11 @@ import ( // 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). +// +// Advise runs off the poll goroutine (hivecommons/hive#17153): at most one call +// per agent is in flight, new scopes queue newest-first behind it, and a result +// is held in the kick state until a later tick passes the delivery gates. A +// result that comes back after the agent's kick moved is dropped. const ( // knowledgeAdvisorDefaultMaxPerKick is the per-kick delivery cap when the @@ -41,8 +47,17 @@ const ( knowledgeAdvisorTrigger = "knowledge-advisor" knowledgeAdvisorKindPath = "path" knowledgeAdvisorKindGH = "gh" + // knowledgeAdvisorDefaultPaneLines caps KnowledgeScope.PaneTail when the + // policy asks for it without a size. + knowledgeAdvisorDefaultPaneLines = 80 ) +// knowledgeAdvisorAdviseGrace is how long a poll tick waits for an Advise call +// it started before leaving the result for a later tick. A bounded local +// matcher answers well inside it, so its advice still lands on the tick that +// saw the scope; a model-backed adviser does not hold the tick past it. +var knowledgeAdvisorAdviseGrace = 500 * time.Millisecond + // 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", @@ -52,7 +67,16 @@ const ( 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`) +// The optional second group is the command within the family ("checks" in +// "gh pr checks"); a new command is what makes a gh scope eligible again. +var knowledgeGHRe = regexp.MustCompile(`\bgh (pr|issue|run|api|release|workflow)\b(?:[ \t]+([a-z][a-z-]*))?`) + +// knowledgeEditLineRe matches the tool-call lines the CLIs print for a file +// write: "● Edit src/x.go", "⏺ Update(src/x.go)", "⏺ Write(src/x.go)". +var knowledgeEditLineRe = regexp.MustCompile(`^\s*[⏺●]\s*(?:Edit|MultiEdit|Write|Update|Create)\b`) + +// knowledgeShellLineRe matches a shell command line: "$ cat src/x.md". +var knowledgeShellLineRe = regexp.MustCompile(`^\s*\$ `) // knowledgeIgnoredDirs are path roots that are tooling, not the agent's work. var knowledgeIgnoredDirs = map[string]bool{ @@ -87,6 +111,10 @@ type knowledgeAdvisor struct { now func() time.Time mu sync.Mutex agents map[string]*knowledgeKickState + // inFlight holds, per agent, the done channel of the Advise call running + // now. It is per agent, not per kick, so a call left over from the + // previous kick still blocks a second concurrent one. + inFlight map[string]chan struct{} } // knowledgeKickState is one agent's advisor state for one kick. It is @@ -95,13 +123,31 @@ type knowledgeAdvisor struct { 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 + seen map[string]*knowledgeScopeSeen // scope keys from the baseline or already handled + delivered map[string]bool // slugs typed this kick count int lastAt time.Time + queue []crux.KnowledgeScope // scopes waiting for Advise, newest first pending []crux.KnowledgeAdvice } +// knowledgeScopeSeen is what one kick has seen of one scope. A scope first +// seen without an edit (or a gh family with only the commands seen so far) is +// eligible for exactly one more Advise call: on its first edit, or on the next +// command in its gh family. Elapsed time never makes it eligible again. +type knowledgeScopeSeen struct { + edited bool + commands map[string]bool + readvised bool +} + +// knowledgeObservation is one scope a pane shows, with the gh commands seen +// in its family. +type knowledgeObservation struct { + scope crux.KnowledgeScope + commands []string +} + // 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) { @@ -110,9 +156,10 @@ func (m *Manager) SetKnowledgeAdviser(adviser crux.KnowledgeAdviser) { return } m.knowledgeAdvisor.Store(&knowledgeAdvisor{ - adviser: adviser, - now: time.Now, - agents: make(map[string]*knowledgeKickState), + adviser: adviser, + now: time.Now, + agents: make(map[string]*knowledgeKickState), + inFlight: make(map[string]chan struct{}), }) } @@ -133,6 +180,7 @@ func (m *Manager) adviseKnowledge(agent *AgentProcess, scrollback, visible strin return } if m.tmuxSessionHasAttachedClientForAgent(agent) { + // Held, not dropped: a later tick delivers it once the human leaves. return } line := renderKnowledgeAdvice(advice) @@ -145,32 +193,32 @@ func (m *Manager) adviseKnowledge(agent *AgentProcess, scrollback, visible strin 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. +// collect folds this tick's scrollback into the agent's kick state, queues +// every scope that is new (or newly eligible) since the baseline for the +// adviser, and returns the next deliverable advice when the cap, cooldown and +// pane gates all allow it. The advice stays pending until markDelivered. func (ka *knowledgeAdvisor) collect(name string, kickAt time.Time, scrollback, visible string, policy crux.KnowledgeAdvisorPolicy) (crux.KnowledgeAdvice, bool) { - scopes := observedKnowledgeScopes(scrollback) + observed := observeKnowledge(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{}} + st = &knowledgeKickState{kickAt: kickAt, seen: map[string]*knowledgeScopeSeen{}, 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 + for _, ob := range observed { + st.seen[ob.scope.Key] = newKnowledgeScopeSeen(ob) } 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 + for _, ob := range observed { + if sc, ok := st.observe(ob); ok { fresh = append(fresh, sc) } } @@ -178,37 +226,28 @@ func (ka *knowledgeAdvisor) collect(name string, kickAt time.Time, scrollback, v if maxPerKick <= 0 { maxPerKick = knowledgeAdvisorDefaultMaxPerKick } - capped := st.count >= maxPerKick + st.enqueue(fresh, maxPerKick-st.count) 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.dispatch(name, st, scrollback, policy) 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 + st.queue = nil return crux.KnowledgeAdvice{}, false } if knowledgeToolInFlight(visible) { return crux.KnowledgeAdvice{}, false } + if st.count >= maxPerKick { + return crux.KnowledgeAdvice{}, false + } cooldown := policy.Cooldown if cooldown <= 0 { cooldown = knowledgeAdvisorDefaultCooldown @@ -216,12 +255,128 @@ func (ka *knowledgeAdvisor) collect(name string, kickAt time.Time, scrollback, v 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 + return st.pending[0], true +} + +func newKnowledgeScopeSeen(ob knowledgeObservation) *knowledgeScopeSeen { + seen := &knowledgeScopeSeen{edited: ob.scope.Action == crux.KnowledgeActionEdit, commands: map[string]bool{}} + for _, c := range ob.commands { + seen.commands[c] = true + } + return seen +} + +// observe records one observation against the kick and reports the scope to +// ask the adviser about: on first sight, and once more on the scope's first +// edit or the next command in its gh family. +func (st *knowledgeKickState) observe(ob knowledgeObservation) (crux.KnowledgeScope, bool) { + seen := st.seen[ob.scope.Key] + if seen == nil { + st.seen[ob.scope.Key] = newKnowledgeScopeSeen(ob) + return ob.scope, true + } + again := false + if ob.scope.Action == crux.KnowledgeActionEdit && !seen.edited { + seen.edited = true + again = true + } + for _, c := range ob.commands { + if !seen.commands[c] { + seen.commands[c] = true + again = true + } + } + if !again || seen.readvised { + return crux.KnowledgeScope{}, false + } + seen.readvised = true + return ob.scope, true +} + +// enqueue puts scopes (in pane order, so the last is the newest) at the head +// of the queue newest-first and caps the queue at the remaining per-kick +// allowance, dropping the oldest. +func (st *knowledgeKickState) enqueue(scopes []crux.KnowledgeScope, remaining int) { + if remaining <= 0 { + st.queue = nil + return + } + queue := make([]crux.KnowledgeScope, 0, len(scopes)+len(st.queue)) + for i := len(scopes) - 1; i >= 0; i-- { + queue = append(queue, scopes[i]) + } + queue = append(queue, st.queue...) + if len(queue) > remaining { + queue = queue[:remaining] + } + st.queue = queue +} + +// dispatch starts the next queued Advise call when none is in flight for the +// agent, and waits up to knowledgeAdvisorAdviseGrace for calls to finish so a +// fast adviser's results land on this tick. It never runs two calls for one +// agent at once and never holds the tick past the grace period. +func (ka *knowledgeAdvisor) dispatch(name string, st *knowledgeKickState, scrollback string, policy crux.KnowledgeAdvisorPolicy) { + deadline := time.Now().Add(knowledgeAdvisorAdviseGrace) + for { + ka.mu.Lock() + done := ka.inFlight[name] + if done == nil { + if len(st.queue) == 0 { + ka.mu.Unlock() + return + } + scope := st.queue[0] + st.queue = st.queue[1:] + if policy.WantsPaneTail { + scope.PaneTail = knowledgePaneTail(scrollback, policy.PaneLines) + } + done = make(chan struct{}) + ka.inFlight[name] = done + go ka.advise(name, st.kickAt, scope, done) + } + ka.mu.Unlock() + + wait := time.Until(deadline) + if wait <= 0 { + return + } + timer := time.NewTimer(wait) + select { + case <-done: + timer.Stop() + case <-timer.C: + return + } + } +} + +// advise runs one Advise call off the poll goroutine and folds its result +// into the agent's kick state, unless the kick captured when the call was +// 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) + + ka.mu.Lock() + defer ka.mu.Unlock() + if ka.inFlight[name] == done { + delete(ka.inFlight, name) + } + st := ka.agents[name] + if st == nil || !st.kickAt.Equal(kickAt) { + return + } + for _, adv := range found { + if adv.Slug == "" || st.delivered[adv.Slug] || knowledgeAdvicePending(st.pending, adv.Slug) { + continue + } + st.pending = append(st.pending, adv) + } } -// markDelivered records a typed slug against the agent's current kick. +// markDelivered records a typed slug against the agent's current kick and +// takes it off the pending list. func (ka *knowledgeAdvisor) markDelivered(name, slug string) { ka.mu.Lock() defer ka.mu.Unlock() @@ -229,11 +384,30 @@ func (ka *knowledgeAdvisor) markDelivered(name, slug string) { if st == nil { return } + for i, p := range st.pending { + if p.Slug == slug { + st.pending = append(st.pending[:i:i], st.pending[i+1:]...) + break + } + } st.delivered[slug] = true st.count++ st.lastAt = ka.now() } +// knowledgePaneTail is the last lines of scrollback with tokens redacted, the +// only pane text that may cross the adviser seam. +func knowledgePaneTail(scrollback string, lines int) string { + if lines <= 0 { + lines = knowledgeAdvisorDefaultPaneLines + } + all := strings.Split(strings.TrimRight(scrollback, "\n"), "\n") + if len(all) > lines { + all = all[len(all)-lines:] + } + return logscrub.RedactPaneTokens(strings.Join(all, "\n")) +} + func knowledgeAdvicePending(pending []crux.KnowledgeAdvice, slug string) bool { for _, p := range pending { if p.Slug == slug { @@ -255,31 +429,82 @@ func knowledgeToolInFlight(visible string) bool { } // observedKnowledgeScopes extracts the scopes a pane capture shows the agent -// working in, in first-seen order, one entry per key. +// working in, in first-seen order, one entry per key. A path scope's Action is +// "edit" if any line edits in it, otherwise the action of its first line. 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] { + for _, ob := range observeKnowledge(pane) { + out = append(out, ob.scope) + } + return out +} + +// observeKnowledge is observedKnowledgeScopes plus, for each gh family, the +// commands seen in it. +func observeKnowledge(pane string) []knowledgeObservation { + pane = stripExplainLines(pane) + var out []knowledgeObservation + index := map[string]int{} + add := func(sc crux.KnowledgeScope, command string) { + if sc.Key == "" { return } - seen[sc.Key] = true - out = append(out, sc) + i, ok := index[sc.Key] + if !ok { + i = len(out) + index[sc.Key] = i + out = append(out, knowledgeObservation{scope: sc}) + } else if sc.Action == crux.KnowledgeActionEdit { + out[i].scope.Action = crux.KnowledgeActionEdit + } + if command != "" && !containsString(out[i].commands, command) { + out[i].commands = append(out[i].commands, command) + } } - for _, match := range knowledgePathRe.FindAllStringSubmatch(pane, -1) { - add(knowledgePathScope(match[1])) + var gh [][]string + for _, line := range strings.Split(pane, "\n") { + action := knowledgeLineAction(line) + for _, match := range knowledgePathRe.FindAllStringSubmatch(line, -1) { + sc := knowledgePathScope(match[1]) + sc.Action = action + add(sc, "") + } + gh = append(gh, knowledgeGHRe.FindAllStringSubmatch(line, -1)...) } - for _, match := range knowledgeGHRe.FindAllStringSubmatch(pane, -1) { + // gh families follow the path scopes, as they always have. + for _, match := range gh { add(crux.KnowledgeScope{ Kind: knowledgeAdvisorKindGH, Key: "gh:" + match[1], Keywords: knowledgeGHKeywords[match[1]], - }) + Action: crux.KnowledgeActionRun, + }, match[2]) } return out } +// knowledgeLineAction tags the pane line an observation came from: a CLI +// write tool is an edit, a shell command is a run, anything else a read. +func knowledgeLineAction(line string) string { + switch { + case knowledgeEditLineRe.MatchString(line): + return crux.KnowledgeActionEdit + case knowledgeShellLineRe.MatchString(line): + return crux.KnowledgeActionRun + default: + return crux.KnowledgeActionRead + } +} + +func containsString(list []string, s string) bool { + for _, v := range list { + if v == s { + return true + } + } + return false +} + // 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 { diff --git a/src/crux/agent/knowledge_advisor_test.go b/src/crux/agent/knowledge_advisor_test.go index 110968f430..0b8b824a9a 100644 --- a/src/crux/agent/knowledge_advisor_test.go +++ b/src/crux/agent/knowledge_advisor_test.go @@ -3,11 +3,13 @@ package agent import ( "reflect" "strings" + "sync" "testing" "time" "github.com/hivecommons/hive/crux" "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/logscrub" ) // knowledge_advisor_test.go covers the mid-task knowledge advisor (#17052): @@ -21,12 +23,14 @@ type fakeAdviser struct { policy crux.KnowledgeAdvisorPolicy byKey map[string][]crux.KnowledgeAdvice asked []string + scopes []crux.KnowledgeScope } 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) + f.scopes = append(f.scopes, scope) return f.byKey[scope.Key] } @@ -320,3 +324,289 @@ func TestAdviseKnowledge_Refusals(t *testing.T) { } }) } + +// blockingAdviser holds every Advise call until the test releases it, and +// records how many calls ran at once. +type blockingAdviser struct { + policy crux.KnowledgeAdvisorPolicy + byKey map[string][]crux.KnowledgeAdvice + release chan struct{} + + mu sync.Mutex + asked []string + running int + maxActive int +} + +func newBlockingAdviser(byKey map[string][]crux.KnowledgeAdvice) *blockingAdviser { + return &blockingAdviser{policy: enabledPolicy(), byKey: byKey, release: make(chan struct{}, 16)} +} + +func (b *blockingAdviser) Policy(string) crux.KnowledgeAdvisorPolicy { return b.policy } + +func (b *blockingAdviser) Advise(_ string, scope crux.KnowledgeScope) []crux.KnowledgeAdvice { + b.mu.Lock() + b.asked = append(b.asked, scope.Key) + b.running++ + if b.running > b.maxActive { + b.maxActive = b.running + } + b.mu.Unlock() + <-b.release + b.mu.Lock() + b.running-- + b.mu.Unlock() + return b.byKey[scope.Key] +} + +func (b *blockingAdviser) snapshot() ([]string, int) { + b.mu.Lock() + defer b.mu.Unlock() + return append([]string(nil), b.asked...), b.maxActive +} + +// waitKnowledgeIdle waits until no Advise call is in flight for agent. +func waitKnowledgeIdle(t *testing.T, m *Manager, agent string) { + t.Helper() + ka := m.knowledgeAdvisor.Load() + deadline := time.Now().Add(5 * time.Second) + for time.Now().Before(deadline) { + ka.mu.Lock() + busy := ka.inFlight[agent] != nil + ka.mu.Unlock() + if !busy { + return + } + time.Sleep(5 * time.Millisecond) + } + t.Fatal("advise call still in flight") +} + +func TestAdviseKnowledge_AsyncOneCallInFlight(t *testing.T) { + adv := newBlockingAdviser(map[string][]crux.KnowledgeAdvice{ + "src/a": {{Slug: "a1", Title: "A1"}}, + "src/b": {{Slug: "b1", Title: "B1"}}, + }) + m, a, typed := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) // baseline + + // The adviser blocks far past the 3 s poll interval; the tick must not. + start := time.Now() + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)", workingPane) + if elapsed := time.Since(start); elapsed > knowledgeAdvisorAdviseGrace+time.Second { + t.Fatalf("tick blocked on Advise for %v", elapsed) + } + // A second scope while the first call runs is queued, not called. + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)\n⏺ Read(src/b/y.go)", workingPane) + if asked, _ := adv.snapshot(); !reflect.DeepEqual(asked, []string{"src/a"}) { + t.Fatalf("asked = %v, want only src/a in flight", asked) + } + if len(*typed) != 0 { + t.Fatalf("typed before any result: %v", *typed) + } + + adv.release <- struct{}{} + waitKnowledgeIdle(t, m, a.Name) + // The held result goes out on the next tick, which also starts src/b. + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)\n⏺ Read(src/b/y.go)", workingPane) + if len(*typed) != 1 || (*typed)[0] != "📚 Knowledge: A1" { + t.Fatalf("typed = %v", *typed) + } + adv.release <- struct{}{} + waitKnowledgeIdle(t, m, a.Name) + asked, maxActive := adv.snapshot() + if !reflect.DeepEqual(asked, []string{"src/a", "src/b"}) { + t.Errorf("asked = %v", asked) + } + if maxActive != 1 { + t.Errorf("%d Advise calls ran at once, want 1", maxActive) + } +} + +func TestAdviseKnowledge_QueueNewestFirstCappedAtAllowance(t *testing.T) { + adv := newBlockingAdviser(nil) + m, a, _ := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)", workingPane) // in flight + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)\n⏺ Read(src/b/x.go)\n⏺ Read(src/c/x.go)\n⏺ Read(src/d/x.go)", workingPane) + + ka := m.knowledgeAdvisor.Load() + ka.mu.Lock() + var queued []string + for _, sc := range ka.agents[a.Name].queue { + queued = append(queued, sc.Key) + } + ka.mu.Unlock() + // MaxPerKick is 2: the two newest scopes wait, newest first. + if want := []string{"src/d", "src/c"}; !reflect.DeepEqual(queued, want) { + t.Errorf("queue = %v, want %v", queued, want) + } + for i := 0; i < 3; i++ { + adv.release <- struct{}{} + } + waitKnowledgeIdle(t, m, a.Name) +} + +func TestAdviseKnowledge_ResultAfterNewKickDropped(t *testing.T) { + adv := newBlockingAdviser(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)", workingPane) // in flight + + later := a.LastKick.Add(time.Hour) + a.LastKick = &later + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) // new kick's baseline + adv.release <- struct{}{} + waitKnowledgeIdle(t, m, a.Name) + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 0 { + t.Fatalf("advice from the previous kick was typed: %v", *typed) + } +} + +func TestObservedKnowledgeScopesAction(t *testing.T) { + pane := strings.Join([]string{ + "⏺ Read(src/crux/agent/manager.go)", + "● Edit src/pkg/config/config.go", + "⏺ Read(src/pkg/config/load.go)", + "⏺ Write(src/docs/new/page.md)", + "$ cat src/scripts/check.sh", + "$ gh pr checks 17153", + }, "\n") + got := map[string]string{} + for _, sc := range observedKnowledgeScopes(pane) { + got[sc.Key] = sc.Action + } + want := map[string]string{ + "src/crux/agent": crux.KnowledgeActionRead, + "src/pkg/config": crux.KnowledgeActionEdit, + "src/docs/new": crux.KnowledgeActionEdit, + "src/scripts": crux.KnowledgeActionRun, + "gh:pr": crux.KnowledgeActionRun, + } + if !reflect.DeepEqual(got, want) { + t.Errorf("actions = %v, want %v", got, want) + } + // A later edit upgrades a scope first seen read. + if sc := observedKnowledgeScopes("⏺ Read(src/a/x.go)\n⏺ Update(src/a/y.go)")[0]; sc.Action != crux.KnowledgeActionEdit { + t.Errorf("read then update = %q, want edit", sc.Action) + } +} + +func TestAdviseKnowledge_ReadviseOncePerScope(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy()} + m, a, _ := advisorManager(t, adv) + now := fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + + pane := "⏺ Read(src/a/x.go)" + m.adviseKnowledge(a, pane, workingPane) + // Time alone never makes a scope eligible again. + *now = now.Add(time.Hour) + m.adviseKnowledge(a, pane, workingPane) + pane += "\n● Edit src/a/x.go" + m.adviseKnowledge(a, pane, workingPane) + pane += "\n⏺ Write(src/a/z.go)" + m.adviseKnowledge(a, pane, workingPane) + + pane += "\n$ gh pr view 1" + m.adviseKnowledge(a, pane, workingPane) + m.adviseKnowledge(a, pane, workingPane) + pane += "\n$ gh pr checks 1" + m.adviseKnowledge(a, pane, workingPane) + pane += "\n$ gh pr merge 1" + m.adviseKnowledge(a, pane, workingPane) + + var got []string + for _, sc := range adv.scopes { + got = append(got, sc.Key+"/"+sc.Action) + } + want := []string{"src/a/read", "src/a/edit", "gh:pr/run", "gh:pr/run"} + if !reflect.DeepEqual(got, want) { + t.Errorf("advised = %v, want %v", got, want) + } +} + +func TestAdviseKnowledge_PaneTailOnlyWhenWanted(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy()} + m, a, _ := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + m.adviseKnowledge(a, "⏺ Read(src/a/x.go)\n$ gh pr view 1", workingPane) + if len(adv.scopes) != 2 { + t.Fatalf("asked %v", adv.asked) + } + for _, sc := range adv.scopes { + if sc.PaneTail != "" { + t.Errorf("scope %s carried pane text without WantsPaneTail: %q", sc.Key, sc.PaneTail) + } + } +} + +func TestAdviseKnowledge_PaneTailScrubbedAndCapped(t *testing.T) { + adv := &fakeAdviser{policy: enabledPolicy()} + adv.policy.WantsPaneTail = true + adv.policy.PaneLines = 3 + m, a, _ := advisorManager(t, adv) + fakeClock(m, time.Date(2026, 11, 7, 12, 1, 0, 0, time.UTC)) + m.adviseKnowledge(a, "", workingPane) + + agentKey := "sk-hive-" + a.Name + ghToken := "ghp_" + strings.Repeat("A1b2", 9) + pane := strings.Join([]string{ + "first line falls off the tail", + "$ export ANTHROPIC_API_KEY='" + agentKey + "'", + "$ GH_TOKEN=" + ghToken + " gh pr view 1", + "⏺ Read(src/a/x.go)", + }, "\n") + "\n" + m.adviseKnowledge(a, pane, workingPane) + if len(adv.scopes) == 0 { + t.Fatal("adviser not asked") + } + for _, sc := range adv.scopes { + tail := sc.PaneTail + if strings.Contains(tail, agentKey) || strings.Contains(tail, ghToken) { + t.Errorf("scope %s pane tail leaks a token: %q", sc.Key, tail) + } + if logscrub.RedactPaneTokens(tail) != tail { + t.Errorf("scope %s pane tail is not scrubbed: %q", sc.Key, tail) + } + if strings.Contains(tail, "first line") || strings.Count(tail, "\n") != 2 { + t.Errorf("scope %s pane tail not capped at 3 lines: %q", sc.Key, tail) + } + if !strings.Contains(tail, "⏺ Read(src/a/x.go)") { + t.Errorf("scope %s pane tail lost the work line: %q", sc.Key, tail) + } + } +} + +func TestKnowledgePaneTailDefaultLines(t *testing.T) { + var lines []string + for i := 0; i < 100; i++ { + lines = append(lines, "line") + } + if got := strings.Count(knowledgePaneTail(strings.Join(lines, "\n"), 0), "\n") + 1; got != knowledgeAdvisorDefaultPaneLines { + t.Errorf("default tail is %d lines, want %d", got, knowledgeAdvisorDefaultPaneLines) + } +} + +func TestAdviseKnowledge_AttachedHumanHoldsAdvice(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) + termSeams(m).sessionAttached = func(*AgentProcess) bool { return true } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + termSeams(m).sessionAttached = func(*AgentProcess) bool { return false } + m.adviseKnowledge(a, "⏺ Edit(src/a/x.go)", workingPane) + if len(*typed) != 1 || (*typed)[0] != "📚 Knowledge: A1" { + t.Fatalf("held advice not delivered after the human left: %v", *typed) + } +} diff --git a/src/crux/knowledge_advice.go b/src/crux/knowledge_advice.go index a7b5aa3882..1f754e9161 100644 --- a/src/crux/knowledge_advice.go +++ b/src/crux/knowledge_advice.go @@ -16,8 +16,21 @@ type KnowledgeScope struct { Path string // Keywords are the search terms the scope contributes to the matcher. Keywords []string + // Action is what the pane line that produced this observation shows the + // agent doing in the scope: "read", "edit" or "run" (hivecommons/hive#17153). + Action string + // PaneTail is the last PaneLines lines of the agent's scrollback, with + // tokens redacted, filled only when the policy sets WantsPaneTail. + PaneTail string } +// Knowledge scope actions. +const ( + KnowledgeActionRead = "read" + KnowledgeActionEdit = "edit" + KnowledgeActionRun = "run" +) + // 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 { @@ -46,6 +59,11 @@ type KnowledgeAdvisorPolicy struct { // Cooldown is the minimum gap between two deliveries to one agent; // non-positive means the default. Cooldown time.Duration + // WantsPaneTail asks the runtime to fill KnowledgeScope.PaneTail. False + // means no pane text crosses the seam. + WantsPaneTail bool + // PaneLines caps PaneTail; non-positive means the default (80). + PaneLines int } // KnowledgeAdviser is the hive side of the mid-task knowledge advisor. @@ -54,6 +72,8 @@ type KnowledgeAdviser interface { 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. + // best first. The runtime calls it on its own goroutine, at most one call + // in flight per agent, so a slow adviser never stalls the poll tick; the + // result is dropped if the agent's kick has changed by the time it returns. Advise(agent string, scope KnowledgeScope) []KnowledgeAdvice } diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index 09aa7aa40b..2567413a4e 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -106,6 +106,15 @@ knowledge toggle registers/unregisters the primer live (`knowledgePrimerControl`). `knowledge.enabled: false` or an empty keyword set means the kick simply has no knowledge section. +**Mid-task advisor.** After the kick, the opt-in advisor (`knowledge.advisor`) +types one `📚 Knowledge:` line when the pane shows the agent entering a new +scope. Each scope is tagged `read`, `edit` or `run` from its pane line and +asked about at most twice per kick: on first sight, and on its first edit or +next `gh` command. The adviser runs off the poll goroutine with one call in +flight per agent. A result is held until a tick passes the delivery gates and +dropped if the kick changed meanwhile. See +[knowledge-curator.md](knowledge-curator.md#mid-task-knowledge-advisor-knowledgeadvisor). + ## 2. Knowledge: pull access Agents (and external tools) can fetch what the primer did not push: diff --git a/src/docs/design/crux.md b/src/docs/design/crux.md index e51a7df08b..836b2cb8dc 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` 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 | +| `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 | 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 d12d8189c2..8fca843552 100644 --- a/src/docs/knowledge-curator.md +++ b/src/docs/knowledge-curator.md @@ -667,8 +667,26 @@ Rules, all enforced by the runtime (`crux/agent/knowledge_advisor.go`): - **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 + also held while a human is attached to the pane and while a kick is being typed. +- **Never stalls the poll tick.** The adviser is called on its own + goroutine, at most one call in flight per agent (hivecommons/hive#17153). + Scopes seen while a call runs queue newest first, capped at the lines + left in the kick's allowance. The tick waits briefly for a fast matcher + so its line still lands on the tick that saw the scope. A slower result + is held until a later tick passes the gates above. A result that comes + back after the agent's kick changed is dropped. +- **Each scope is tagged with an action and asked about at most twice per + kick.** The pane line a scope comes from gives its `Action`: + `⏺ Read(…)` is `read`, `● Edit …` / `Write` / `Update` is `edit`, and a + `$ …` shell line (such as `$ gh pr …`) is `run`. The adviser is asked on + the scope's first sighting, and once more on the first `edit` in a scope + first seen without one, or on the next command in a `gh` family. A third + sighting is ignored, and elapsed time never makes a scope eligible again. +- **No pane text unless the adviser asks.** An adviser whose policy sets + `WantsPaneTail` receives the last `PaneLines` (default 80) scrollback + lines, passed through `logscrub.RedactPaneTokens` first. Phase 1's + matcher never asks, so no pane text leaves the runtime. - **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 From 80d3249ef5d7df9dee6f13cdb161563241932a43 Mon Sep 17 00:00:00 2001 From: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Sat, 7 Nov 2026 21:18:14 -0500 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20crux:=20wait=20for=20adviser?= =?UTF-8?q?=20idle=20with=20testutil.Eventually,=20not=20a=20fixed=20sleep?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TestSleepRatchet pins the count of time.Sleep calls in tests; the new waitKnowledgeIdle helper polled with one. Use the package's Eventually helper instead. Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> --- src/crux/agent/knowledge_advisor_test.go | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/crux/agent/knowledge_advisor_test.go b/src/crux/agent/knowledge_advisor_test.go index 0b8b824a9a..b23af49723 100644 --- a/src/crux/agent/knowledge_advisor_test.go +++ b/src/crux/agent/knowledge_advisor_test.go @@ -9,6 +9,7 @@ import ( "github.com/hivecommons/hive/crux" "github.com/hivecommons/hive/crux/config" + "github.com/hivecommons/hive/crux/internal/testutil" "github.com/hivecommons/hive/crux/logscrub" ) @@ -369,17 +370,11 @@ func (b *blockingAdviser) snapshot() ([]string, int) { func waitKnowledgeIdle(t *testing.T, m *Manager, agent string) { t.Helper() ka := m.knowledgeAdvisor.Load() - deadline := time.Now().Add(5 * time.Second) - for time.Now().Before(deadline) { + testutil.Eventually(t, 5*time.Second, func() bool { ka.mu.Lock() - busy := ka.inFlight[agent] != nil - ka.mu.Unlock() - if !busy { - return - } - time.Sleep(5 * time.Millisecond) - } - t.Fatal("advise call still in flight") + defer ka.mu.Unlock() + return ka.inFlight[agent] == nil + }, "advise call still in flight") } func TestAdviseKnowledge_AsyncOneCallInFlight(t *testing.T) {