Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-kick-knowledge-log-line.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Every primed kick now logs one `knowledge: injected N bytes from M entries (skipped K for cap)` line with the primer cap and the sizes of the AGENTS.md and skills blocks, so the knowledge share of a kick is measurable next to `kick rendered` (#17049).
8 changes: 8 additions & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -873,6 +873,14 @@ level=INFO msg="kick rendered" agent=scanner repo="" kick_bytes=58123 issues_tot

`kick_bytes` is the prompt as typed (canary preamble included). When `issues_listed` / `prs_listed` sit well below the caps on every kick, lowering them changes nothing; when `*_total` is persistently far above `*_listed`, the backlog — not the cap — is the problem, and the overflow marker in the prompt already tells the agent the list is partial. Per-agent kicks share the same global caps; set them under **Settings → Repos → Kick prompt list caps** or in `governor.kick_limits`, with `0` meaning unlimited.

**The knowledge share of a kick.** Next to `kick rendered`, each kick that was primed logs one knowledge line ([#17049](https://github.com/hivecommons/hive/issues/17049)):

```
level=INFO msg="knowledge: injected 3900 bytes from 7 entries (skipped 3 for cap)" agent=developer injected_bytes=3900 entries=7 skipped_for_cap=3 cap_bytes=4096 primed=true agents_md_bytes=1980 skills_bytes=0
```

`injected_bytes` / `entries` are the rendered `# Relevant Knowledge` block; `skipped_for_cap` counts relevant facts dropped whole because they did not fit `knowledge.primer.max_bytes` (`cap_bytes`); `agents_md_bytes` and `skills_bytes` are the repository `AGENTS.md` block and the requested-skills block that share the kick. A zero line (`primed=true`, 0 entries) means priming ran and found nothing relevant — the signal that the store lacks entries for that lane's work. The line is not emitted when knowledge is disabled or there was nothing to prime, so a hive without a knowledge store does not log a zero on every kick. Read it against `src/docs/knowledge-entries.md` when deciding whether a fact belongs in `AGENTS.md` (paid on every kick) or in a scoped entry (paid only when it matches).

### What consumes tokens while agents are paused

Pausing agents (including the navbar fleet breaker) does not take the Hive instance down: the dashboard, governor scans, GitHub polling, token scanners, repo-cost collectors, telemetry/heartbeats, and provider-headroom probes can keep running. Those components should not make model calls by themselves. Model usage is expected from agent sessions reached through governor/manual/CEL/resume kicks; those kick paths share the same pause and budget gates. Knowledge priming reads configured knowledge stores and attaches facts to kicks; it does not independently call the model while every agent is paused. Provider-budget probes are the exception by design: after a provider spend-limit rebuff, Hive may release one kick after `governor.provider_budget.probe_interval_s` to test recovery.
Expand Down
69 changes: 62 additions & 7 deletions src/pkg/scheduler/kick_priming.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ import (
"strings"

"github.com/hivecommons/hive/crux/agentsmd"
"github.com/hivecommons/hive/crux/skillreg"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/knowledge"
"github.com/hivecommons/hive/crux/skillreg"
)

const maxIssuesToPrime = 5
Expand Down Expand Up @@ -250,16 +250,40 @@ func capSkills(skills []skillreg.Skill, capBytes int) (kept []skillreg.Skill, dr
return kept, dropped
}

// knowledgeInjection is what one kick received from the knowledge primer
// (#17049): the rendered "# Relevant Knowledge" section and the numbers
// behind it. Primed is false when the primer did not run at all (knowledge
// disabled, no issues, no keywords), so a zero-byte result from a real query
// is distinguishable from no query.
type knowledgeInjection struct {
Section string
Bytes int
Entries int
SkippedForCap int
CapBytes int
Primed bool
}

// primeKnowledge queries the wiki layers for facts relevant to the given issues
// and returns a formatted section for injection into the kick message. The
// facts are restricted to agentName's knowledge.agent_scopes entry, if any.
// It logs the per-kick knowledge line itself; callers that also prepend an
// AGENTS.md or skills block use primeKnowledgeStats and log once with those
// sizes included.
func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) string {
inj := s.primeKnowledgeStats(agentName, issues)
s.logKnowledgeInjection(agentName, inj, 0, 0)
return inj.Section
}

// primeKnowledgeStats is primeKnowledge without the summary log line.
func (s *Scheduler) primeKnowledgeStats(agentName string, issues []github.Issue) knowledgeInjection {
s.mu.RLock()
primer := s.primer
cfg := s.cfg
s.mu.RUnlock()
if primer == nil || len(issues) == 0 {
return ""
return knowledgeInjection{}
}

limit := maxIssuesToPrime
Expand All @@ -270,7 +294,7 @@ func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) stri
keywords := extractKeywords(issues[:limit])
if len(keywords) == 0 {
s.logger.Debug("knowledge primer: no keywords extracted from issues", "issue_count", len(issues))
return ""
return knowledgeInjection{}
}

s.logger.Info("knowledge primer: searching", "keywords", len(keywords), "sample", keywordSample(keywords))
Expand All @@ -281,9 +305,13 @@ func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) stri
}
primed := primer.PrimeScoped(context.Background(), scope, nil, keywords)
result, omitted := primed.Render()
if result != "" {
s.logger.Info("knowledge primer: injecting facts into kick",
"facts", len(primed.Facts)-omitted.Facts, "chars", len(result))
inj := knowledgeInjection{
Section: result,
Bytes: len(result),
Entries: len(primed.Facts) - omitted.Facts,
SkippedForCap: omitted.Facts,
CapBytes: primer.MaxBytes(),
Primed: true,
}
if omitted.Any() {
// The render carries its own marker; this is the operator-side half so
Expand All @@ -301,7 +329,34 @@ func (s *Scheduler) primeKnowledge(agentName string, issues []github.Issue) stri
"omitted_facts", omitted.Facts, "omitted_hints", omitted.Hints,
"omitted_bytes", omitted.Bytes, "cap_bytes", primed.MaxBytes)
}
return result
return inj
}

// logKnowledgeInjection emits the one knowledge line per kick (#17049):
//
// knowledge: injected N bytes from M entries (skipped K for cap)
//
// with the primer cap and the sizes of the AGENTS.md and skills blocks that
// share the kick, so the whole knowledge payload is readable from one line
// next to "kick rendered". It is emitted even when N is 0 — a primed kick
// that found nothing is a signal, not silence — but not when the primer did
// not run (knowledge disabled or nothing to prime), which would otherwise
// print a zero line on every kick of a hive that has no knowledge store.
func (s *Scheduler) logKnowledgeInjection(agentName string, inj knowledgeInjection, agentsMdBytes, skillsBytes int) {
if s == nil || s.logger == nil || (!inj.Primed && agentsMdBytes == 0 && skillsBytes == 0) {
return
}
s.logger.Info(fmt.Sprintf("knowledge: injected %d bytes from %d entries (skipped %d for cap)",
inj.Bytes, inj.Entries, inj.SkippedForCap),
"agent", agentName,
"injected_bytes", inj.Bytes,
"entries", inj.Entries,
"skipped_for_cap", inj.SkippedForCap,
"cap_bytes", inj.CapBytes,
"primed", inj.Primed,
"agents_md_bytes", agentsMdBytes,
"skills_bytes", skillsBytes,
)
}

// extractKeywords pulls searchable terms from issue labels and titles.
Expand Down
165 changes: 165 additions & 0 deletions src/pkg/scheduler/kick_priming_log_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
package scheduler

import (
"bytes"
"encoding/json"
"log/slog"
"os"
"path/filepath"
"strings"
"testing"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/github"
"github.com/hivecommons/hive/pkg/knowledge"
)

// knowledgeLogLines returns the decoded "knowledge: injected …" records a
// scheduler wrote to buf.
func knowledgeLogLines(t *testing.T, buf *bytes.Buffer) []map[string]any {
t.Helper()
var out []map[string]any
for _, line := range strings.Split(strings.TrimSpace(buf.String()), "\n") {
if line == "" {
continue
}
var rec map[string]any
if err := json.Unmarshal([]byte(line), &rec); err != nil {
t.Fatalf("bad log line %q: %v", line, err)
}
if msg, _ := rec["msg"].(string); strings.HasPrefix(msg, "knowledge: injected ") {
out = append(out, rec)
}
}
return out
}

func TestLogKnowledgeInjection(t *testing.T) {
tests := []struct {
name string
inj knowledgeInjection
agentsMdBytes int
skillsBytes int
wantLine bool
wantMsg string
}{
{
name: "primer did not run and nothing else injected: silent",
inj: knowledgeInjection{},
wantLine: false,
},
{
name: "primed with nothing found still reports a zero line",
inj: knowledgeInjection{Primed: true, CapBytes: 4096},
wantLine: true,
wantMsg: "knowledge: injected 0 bytes from 0 entries (skipped 0 for cap)",
},
{
name: "primed with omissions plus AGENTS.md and skills",
inj: knowledgeInjection{Primed: true, Bytes: 3900, Entries: 7, SkippedForCap: 3, CapBytes: 4096},
agentsMdBytes: 1980,
skillsBytes: 512,
wantLine: true,
wantMsg: "knowledge: injected 3900 bytes from 7 entries (skipped 3 for cap)",
},
{
name: "no primer but an AGENTS.md block is still a knowledge payload",
inj: knowledgeInjection{},
agentsMdBytes: 1980,
wantLine: true,
wantMsg: "knowledge: injected 0 bytes from 0 entries (skipped 0 for cap)",
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
var buf bytes.Buffer
s := New(&config.Config{}, slog.New(slog.NewJSONHandler(&buf, nil)))
s.logKnowledgeInjection("developer", tc.inj, tc.agentsMdBytes, tc.skillsBytes)
lines := knowledgeLogLines(t, &buf)
if !tc.wantLine {
if len(lines) != 0 {
t.Fatalf("expected no line, got %v", lines)
}
return
}
if len(lines) != 1 {
t.Fatalf("expected exactly one line, got %d: %v", len(lines), lines)
}
rec := lines[0]
if rec["msg"] != tc.wantMsg {
t.Fatalf("msg = %q, want %q", rec["msg"], tc.wantMsg)
}
want := map[string]float64{
"injected_bytes": float64(tc.inj.Bytes),
"entries": float64(tc.inj.Entries),
"skipped_for_cap": float64(tc.inj.SkippedForCap),
"cap_bytes": float64(tc.inj.CapBytes),
"agents_md_bytes": float64(tc.agentsMdBytes),
"skills_bytes": float64(tc.skillsBytes),
}
for k, v := range want {
if got, _ := rec[k].(float64); got != v {
t.Errorf("%s = %v, want %v", k, rec[k], v)
}
}
if rec["agent"] != "developer" {
t.Errorf("agent = %v, want developer", rec["agent"])
}
if rec["primed"] != tc.inj.Primed {
t.Errorf("primed = %v, want %v", rec["primed"], tc.inj.Primed)
}
})
}
}

// TestPrimeKnowledge_LogsOneLinePerKick drives the real primer against a temp
// vault with a cap small enough to drop an entry, and checks that
// primeKnowledge emits exactly one summary line whose numbers match the
// rendered section.
func TestPrimeKnowledge_LogsOneLinePerKick(t *testing.T) {
dir := t.TempDir()
long := strings.Repeat("scheduler kick detail. ", 40)
for i, name := range []string{"scheduler-a.md", "scheduler-b.md", "scheduler-c.md"} {
content := "---\ntitle: Scheduler kick fact " + string(rune('A'+i)) + "\ntype: pattern\nlayer: project\n---\n" + long
if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil {
t.Fatal(err)
}
}
var buf bytes.Buffer
logger := slog.New(slog.NewJSONHandler(&buf, nil))
store, err := knowledge.NewFileStore(dir, "vault", logger)
if err != nil {
t.Fatal(err)
}
// 512 is the primer's floor; three ~250-byte snippets cannot all fit.
p := knowledge.NewPrimer(nil, knowledge.PrimerConfig{MaxBytes: 512}, logger)
p.AddFileStore("vault", store, knowledge.LayerProject)

s := New(&config.Config{}, logger)
s.SetPrimer(p)
issues := []github.Issue{makeIssue("org/repo", 1, "scheduler kick fact", "", 5, nil, false)}

section := s.primeKnowledge("developer", issues)
if section == "" {
t.Fatal("expected a rendered knowledge section")
}
lines := knowledgeLogLines(t, &buf)
if len(lines) != 1 {
t.Fatalf("expected one knowledge line per kick, got %d", len(lines))
}
rec := lines[0]
if int(rec["injected_bytes"].(float64)) != len(section) {
t.Errorf("injected_bytes = %v, want %d", rec["injected_bytes"], len(section))
}
if int(rec["cap_bytes"].(float64)) != 512 {
t.Errorf("cap_bytes = %v, want 512", rec["cap_bytes"])
}
entries := int(rec["entries"].(float64))
skipped := int(rec["skipped_for_cap"].(float64))
if entries < 1 || skipped < 1 || entries+skipped != 3 {
t.Errorf("entries=%d skipped=%d, want both ≥1 and summing to 3", entries, skipped)
}
if strings.Count(section, "- **Scheduler kick fact") != entries {
t.Errorf("section has %d entries, log says %d", strings.Count(section, "- **Scheduler kick fact"), entries)
}
}
10 changes: 7 additions & 3 deletions src/pkg/scheduler/templates.go
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,8 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith
if len(agentIssues) == 0 && actionable != nil && len(actionable.Issues.Items) > 0 {
agentIssues = actionable.Issues.Items
}
knowledgeSection := s.primeKnowledge(agentName, agentIssues)
knowledgeInj := s.primeKnowledgeStats(agentName, agentIssues)
knowledgeSection := knowledgeInj.Section

repoRoot := s.agentsRepoRoot(primaryRepo)

Expand All @@ -378,17 +379,20 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith
// agentsmd.ParseNearest for closest-wins nested AGENTS.md. That still has no
// caller — nothing on the kick path knows which FILE an agent will touch —
// so it stays deferred, unlike the checkout root, which is now threaded.
if agentsSection := s.primeAgentsMd(repoRoot); agentsSection != "" {
agentsSection := s.primeAgentsMd(repoRoot)
if agentsSection != "" {
knowledgeSection = agentsSection + "\n" + knowledgeSection
}

// Agent-declared skills prefer the hive-host-local registry, then fall back
// to definitions in the primary repo's AGENTS.md or adjacent skills/
// directory. The registry remains independently useful without a checkout;
// the fallback activates only when agentsRepoRoot found one above.
if skillsSection := s.primeSkills(agentName, repoRoot); skillsSection != "" {
skillsSection := s.primeSkills(agentName, repoRoot)
if skillsSection != "" {
knowledgeSection = skillsSection + "\n" + knowledgeSection
}
s.logKnowledgeInjection(agentName, knowledgeInj, len(agentsSection), len(skillsSection))

inceptionIdea, inceptionPhase, inceptionMode, inceptionAnswers, inceptionSlug, inceptionRepoURL := s.inceptionVars()

Expand Down
Loading