Skip to content

✨ knowledge advisor: surface scoped knowledge mid-task when an agent's work enters a new scope - #17068

Merged
clubanderson merged 3 commits into
v5from
knowledge-advisor
Nov 7, 2026
Merged

clubanderson merged 3 commits into
v5from
knowledge-advisor

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Phase 1 of the mid-task knowledge advisor — the second half of @gregoryhunt's 2026-11-05 Hive Commons proposal (@Danathar's OMP-advisor comparison). Closes #17052. Phase 2 (LLM-ranked, OMP-style) is #17054.

Today Hive injects # Relevant Knowledge once, at kick time, capped at 4096 bytes. This PR keeps watching after the kick and surfaces scoped knowledge when the agent's work enters a scope that was not on screen when the kick landed — default off (knowledge.advisor: false); the plan in #17052 is to flip it on once hive's own hive has run it for a week.

Signal and delivery (what was already there)

  • Signal: the scrollback the poller already captures every tick in pollTmuxOutputForAgent (src/crux/agent/manager_poll.go). observedKnowledgeScopes pulls directory prefixes (⏺ Read(src/crux/agent/manager.go), ● Edit src/pkg/…, $ cat …) truncated to 3 segments, and gh pr|issue|run|api|release|workflow families. Explain-mode narration is stripped first. No new watcher, no proxy hook.
  • Delivery: the same live-session primitive the CI-poll nudge uses (tmuxSendLiteralForAgent + tmuxSendEntersForAgent, src/crux/agent/manager_tmux.go), with the same baseline-at-first-post-kick-poll trick as nudgeIfPollingCI. One line per entry: 📚 Knowledge: <title> — <≤300 chars> (full: <ref>).
  • Matcher: the kick's own Primer.PrimeScoped under the same knowledge.agent_scopes restriction, with the observed file as the primer's file path and the scope segments as keywords. (✨ knowledge: scope block (paths, labels, lanes) on entries and a kick-context filter in the Primer #17045's kick-context paths plug straight into KnowledgeScope.Path when they land.)

Rules enforced by the runtime (src/crux/agent/knowledge_advisor.go)

  • At most knowledge.advisor_max_per_kick (default 3) per kick, 2-minute cooldown between lines; state resets when LastKick moves.
  • Never an entry the kick already carried: the primer now records which slugs survived the byte cap (PrimedKnowledge.RenderedSlugs, Scheduler.KickPrimedSlugs); a slug is typed at most once per kick.
  • Never while a tool call is running (Running 1 shell command…, OMP's Running… (esc to cancel)) — it waits; if the turn reaches an empty prompt first the pending advice is dropped. Skipped while a human is attached and while a kick is being typed.
  • Per-agent/family opt-out: knowledge.advisor_exclude_agents.
  • Measurement: prompt-history trigger knowledge-advisor + knowledge advisor: delivered log line.

Wiring

  • crux.KnowledgeAdviser host seam, Host.SetKnowledgeAdviser, registered HostSetterInProcessOnly (same class as SetSpanStarter); sidecar returns the in-process-only error, recorder records it, crux/api/client parity test updated. cmd/hive/knowledge_adviser.go adapts the Primer and is installed in bootWatchers next to SetRecordPromptCallback.
  • manager.go gains exactly one field and stays at its file-size-ratchet baseline.

Tests

Table-driven, fake adviser + fake clock, funcTerminal seams, no time.Sleep: scope extraction across Claude Code / Copilot / shell shapes (URLs, absolute paths, root files, tooling dirs excluded), gh families, keywords, the typed line and its cap, pane gates, baseline → new-kick reset, cap, cooldown, slug dedupe, tool-in-flight wait, idle drop, every refusal path. Root module: config parse/default/opt-out, RenderedSlugs vs the byte cap, selectKnowledgeAdvice/truncateRunes/Policy/no-primer path.

Related: #17043 (RFC, sibling), #17045, #17047 — this PR does not touch AGENTS.md or the entry format.

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 7, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kellyaa for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#17060 ✨ knowledge: scope block on entries and a kick-context filter in the Primer same files src/pkg/knowledge/types.go
src/pkg/scheduler/kick_priming.go
#17073 🌱 contributor-nudge once per PR+reason; fold origin notes into status; marker ratchet same files src/docs/operator-reference/README.md
src/pkg/config/config.go
#17040 ✨ agents: disable CLI auto-memory by default and add cli_memory.clear_on_kick same files src/crux/agent/manager.go
src/docs/operator-reference/README.md
src/pkg/config/config.go
src/pkg/dashboard/settings_parity_allowlist.txt
#17072 ✨ review backlog: min_severity floor, per-PR lifetime cap, collapse same-family findings same files src/docs/operator-reference/README.md

@hivecommons-hive

hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

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

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

Failing checks:

  • crux-file-size-ratchet

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

…s work enters a new scope

Phase 1 of the mid-task knowledge advisor (#17052). The
kick primer runs once; this watches the agent's pane on every poll tick,
and the first time a scope (directory prefix or gh command family) shows
up that was not on screen at kick time, asks the same knowledge Primer
under the same agent scope and types one '📚 Knowledge:' line per hit
through the existing live-session primitive used by the CI-poll nudge.

- crux: KnowledgeAdviser host seam (in-process-only, like SetSpanStarter),
  crux/agent/knowledge_advisor.go: baseline at first post-kick poll,
  per-kick cap, cooldown, dedupe against kick-primed slugs, never during
  a tool call or after the turn ends, prompt-history trigger
  knowledge-advisor for measurement.
- hive: cmd/hive/knowledge_adviser.go adapts Primer.PrimeScoped; the
  primer now records which slugs survived the byte cap (RenderedSlugs,
  Scheduler.KickPrimedSlugs) so those are never re-sent.
- config: knowledge.advisor (default off), advisor_max_per_kick (3),
  advisor_exclude_agents.
- docs: knowledge-curator.md section, operator-reference row, crux.md
  HostSetters row.

Phase 2 (LLM-ranked, OMP-style) is #17054.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…t ratchet baselines

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
…rity fixtures, keep manager.go at baseline

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson
clubanderson merged commit e8347bd into v5 Nov 7, 2026
80 of 81 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the knowledge-advisor branch November 7, 2026 19:29
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ knowledge advisor: surface scoped knowledge mid-task when an agent's work enters a new scope

1 participant