Repository navigation
✨ crux: asynchronous KnowledgeAdviser with scope Action and scrubbed PaneTail - #17170
Conversation
…PaneTail Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com> Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com>
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Open PR overlap checkBase branch: Conflicts are checked with every PR merged onto the current tip of
|
|
Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor. hive/awaiting-ci: CI pending — sweep will merge when green. 🐝 Hive Agent: — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 Review findings from Correctness review (head 80d3249) — the async seam matches #17153: one call in flight per agent ( One advisory gap, not blocking:
Review findings from Read the seam change against v5 ( What I verified:
One note, not a defect: a per-kick |
…leep 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>
There was a problem hiding this comment.
Intent alignment (#17153) — approve, one advisory.
The diff covers every scope item in #17153: Action/PaneTail/WantsPaneTail/PaneLines on the seam (src/crux/knowledge_advice.go:19-25, 62-66), one in-flight call per agent via inFlight (src/crux/agent/knowledge_advisor.go dispatch/advise), newest-first queue capped at remaining allowance (enqueue), kick-identity drop (advise compares st.kickAt to captured kickAt), once-only re-advise on first edit / new gh command (observe), scrubbed + capped pane tail (knowledgePaneTail → logscrub.RedactPaneTokens), and the cmd adapter returning WantsPaneTail: false. Tests exist for each acceptance criterion, and src/cmd/hive/knowledge_adviser_test.go is untouched.
Advisory (in-scope, non-blocking): the issue's first acceptance criterion is "a slow Advise does not delay the poll tick". dispatch waits up to knowledgeAdvisorAdviseGrace (500 ms) on every tick while a call is in flight — including ticks that started nothing and have an empty queue, because done := ka.inFlight[name] is non-nil and the select still waits on it. The PR body justifies the grace so that a fast matcher's result lands on the tick that saw the scope, but that rationale only applies to a call started in this dispatch. For a model-backed adviser taking several seconds, every 3 s tick for that agent pays 500 ms for nothing. Suggested follow-up: only enter the wait when this call to dispatch started a goroutine (or when the queue is non-empty), and return immediately when a leftover call is in flight and nothing was dispatched. Bounded and per-agent goroutine (manager_poll.go:16), so not a blocker for this slice.
— hive: agent=adjudicator-3 backend=copilot model=claude-fable-5.1 copilot=1.0.88
Review follow-ups (below
|
There was a problem hiding this comment.
Read the full diff against v5, the poll entry point (manager_poll.go:16, :327-331), and logscrub.RedactPaneTokens (logscrub/pane.go:36). The async seam looks correct to me.
What I checked specifically, because this is the kind of change where the bugs hide in ordering:
- One call in flight per agent.
dispatch(knowledge_advisor.go:308-343) only starts a goroutine whenka.inFlight[name] == nil, andadviseclears the slot underka.mubeforeclose(done)runs — thedefer ka.mu.Unlock()is registered afterdefer close(done), so it fires first. A tick that wakes ondonetherefore sees the slot empty and can start the next queued scope on the same tick. No window for two concurrent calls. - Stale results.
advisecompares the capturedkickAtagainstst.kickAtunder the lock (:357-360); a result arriving after a new kick is dropped.TestAdviseKnowledge_ResultAfterNewKickDroppedcovers it. - Tick blocking.
dispatchcan hold the caller up toknowledgeAdvisorAdviseGrace(500 ms) per tick while a slow adviser is in flight.pollTmuxOutputForAgentis one goroutine per agent, so this only delays that agent's own 3 s tick and nothing else — matches the stated goal. Worth knowing for whoever wires the LLM adviser: a permanently slow backend costs ~17 % of every tick for that agent until it returns, which is bounded but not free. - Pane text across the seam.
PaneTailis filled only whenpolicy.WantsPaneTail(:325-327) and always passes throughRedactPaneTokens; the hive-sideknowledgeAdviser.Policysets itfalseexplicitly (cmd/hive/knowledge_adviser.go:66).TestAdviseKnowledge_PaneTailOnlyWhenWanted/_PaneTailScrubbedAndCappedpin both. - Pending semantics.
collectnow returnsst.pending[0]without popping;markDeliveredremoves it. The attached-human early return inadviseKnowledge(:181-184) therefore holds rather than drops — a deliberate behaviour change, andTestAdviseKnowledge_AttachedHumanHoldsAdviceasserts it.
Minor, not blocking: after knowledgeTurnIdle clears st.pending/st.queue (:245-250), an already-running advise for the same kick will still append its result on return. The next tick clears it again if still idle, or delivers it if the agent resumed, so it is self-correcting — just noting it is not a hard cancel.
No changes requested.
— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Read the runtime change against its caller and the tests; the async seam is sound and the body matches the diff.
Verified
- Poll cadence:
manager_poll.go:16-18runs onepollTmuxOutputForAgentgoroutine per agent on a 3 s ticker, so the 500 msknowledgeAdvisorAdviseGracewait indispatch(knowledge_advisor.go:316-348) is bounded per agent and cannot compound across agents. - One call in flight:
inFlightis keyed by agent, not kick (knowledge_advisor.go:114-117), anddispatchonly starts a call wheninFlight[name] == nil.TestAdviseKnowledge_AsyncOneCallInFlightassertsmaxActive == 1. - Stale results:
advisecompares the capturedkickAtwithka.agents[name].kickAtunderka.mubefore touchingpending(knowledge_advisor.go:354-369); covered byTestAdviseKnowledge_ResultAfterNewKickDropped. - Held-not-popped:
collectnow returnsst.pending[0]without popping andmarkDeliveredremoves it by slug (knowledge_advisor.go:383-396), so the attached-human return atknowledge_advisor.go:182-185no longer loses the entry.TestAdviseKnowledge_AttachedHumanHoldsAdvicecovers it. - Bounded re-advise:
observesetsreadvisedonce and never resets it (knowledge_advisor.go:271-293), so a scope is asked about at most twice per kick, as the docs state. PaneTailonly populated underpolicy.WantsPaneTailand passed throughlogscrub.RedactPaneTokens(logscrub/pane.go:36);cmd/hive/knowledge_adviser.go:66keeps phase 1 atfalse.
One thing worth a comment in code (info, not a defect)
advise (knowledge_advisor.go:354-360) relies on defer LIFO order: ka.mu.Unlock() runs before close(done), so by the time dispatch wakes on <-done the inFlight entry is already gone and it does not spin on a closed channel for the rest of the grace window. It is correct as written, but a future reorder of those two defers would silently reintroduce a busy-wait. A one-line comment would pin the invariant.
Docs (knowledge-curator.md, agent-knowledge-and-memory.md, design/crux.md) and the changelog fragment describe the new behaviour accurately. Looks correct to me.
— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88
There was a problem hiding this comment.
Read the full diff against v5 at merge-base 8e55232, plus the caller adviseKnowledge and logscrub.RedactPaneTokens. This looks correct to me and matches the #17153 scope item for item.
What I verified:
- Handoff is race-free. In
advise(src/crux/agent/knowledge_advisor.go:362-380)defer close(done)is registered beforedefer ka.mu.Unlock(), so the unlock runs first andinFlight[name]is already cleared by the timedispatch's<-donefires and re-takes the lock. The result is folded intoka.agents[name]looked up fresh, and dropped whenkickAtno longer matches — the "new kick" acceptance criterion. - Held-not-lost is real.
collectnow returnsst.pending[0]without popping (:258), andmarkDelivered(:388-394) removes it only after the attached-human check inadviseKnowledge(:182). Previously the pop happened before that check, so this is the fix the body describes. - No pane text crosses by default.
cmd/hive/knowledge_adviser.go:66returnsWantsPaneTail: false, anddispatchonly fillsPaneTailunderpolicy.WantsPaneTail(:323-325), throughknowledgePaneTail→RedactPaneTokens.TestAdviseKnowledge_PaneTailOnlyWhenWantedand..._PaneTailScrubbedAndCappedpin both. - Re-advise is bounded.
observe(:263-286) returns a scope at most twice: first sight, then once on first edit / new gh command, gated byreadvised. Elapsed time is never an input.
One observation, not a defect: while a slow call is in flight, dispatch (:309-345) spends the full 500 ms grace on every tick, including ticks where the queue is empty, because the leftover done is what it waits on. With a 3 s poll that's a bounded ~17% tick cost for the duration of a model-backed call. It is what makes the fast matcher land same-tick, so I'd leave it — just flagging that "does not delay the poll tick" in the issue is "delays it by at most the grace".
— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88
|
Thank you for your contribution! Your PR has been merged. We'd love to hear how your experience was: share feedback |
Phase 1 of the knowledge advisor calls
Advisesynchronously on the agent's 3 s poll goroutine. That is tolerable for a bounded local matcher, but the LLM-ranked adviser planned in #17054 takes seconds per call and would stall everything else that tick serves, including the CI-poll guard. The seam has to change before any model-backed adviser can plug in.This PR changes the seam only.
Advisenow runs off the tick with at most one call in flight per agent, so a slow adviser can never pile up concurrent calls against one agent. Results wait for the same delivery gates as before. A result that returns after the kick moved is dropped, because advice for a finished task is noise in the next one. A short grace wait keeps phase 1's fast matcher delivering on the same tick, so its observable behaviour is unchanged.The
Actiontag and the one-time re-advise on first edit or nextghcommand implement the RFC's timing rule: an adviser that returns nothing on a passing read gets exactly one more chance when the agent is about to act. It never gets one just because time passed, so total calls stay bounded at two per scope per kick.PaneTailis opt-in and scrubbed withlogscrub.RedactPaneTokensbefore it leaves the runtime, because the pane can contain agent API keys and GitHub tokens. Phase 1's policy never requests it, so no pane text crosses the seam today.One related fix: advice found while a human is attached is now held instead of popped and lost, matching the "hold until a later tick passes the gates" contract.
Closes #17153
Part of #17054 (slice 1 of the advisor phase 2 plan; later slices remain open)
— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@clubanderson