diff --git a/changelog.d/added-kick-knowledge-log-line.md b/changelog.d/added-kick-knowledge-log-line.md new file mode 100644 index 0000000000..82df210405 --- /dev/null +++ b/changelog.d/added-kick-knowledge-log-line.md @@ -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). diff --git a/src/docs/operator-reference/sweeps-and-operations.md b/src/docs/operator-reference/sweeps-and-operations.md index 984ee983bc..3fa3be083a 100644 --- a/src/docs/operator-reference/sweeps-and-operations.md +++ b/src/docs/operator-reference/sweeps-and-operations.md @@ -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. diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index 0f689a4167..126f46a789 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -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 @@ -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 @@ -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)) @@ -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 @@ -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. diff --git a/src/pkg/scheduler/kick_priming_log_test.go b/src/pkg/scheduler/kick_priming_log_test.go new file mode 100644 index 0000000000..e356607254 --- /dev/null +++ b/src/pkg/scheduler/kick_priming_log_test.go @@ -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) + } +} diff --git a/src/pkg/scheduler/templates.go b/src/pkg/scheduler/templates.go index d5422987e3..769057bb09 100644 --- a/src/pkg/scheduler/templates.go +++ b/src/pkg/scheduler/templates.go @@ -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) @@ -378,7 +379,8 @@ 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 } @@ -386,9 +388,11 @@ func (s *Scheduler) substituteTemplateWithVars(template string, actionable *gith // 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()