diff --git a/changelog.d/changed-18495-agents-md-cap.md b/changelog.d/changed-18495-agents-md-cap.md new file mode 100644 index 0000000000..a00565cb1d --- /dev/null +++ b/changelog.d/changed-18495-agents-md-cap.md @@ -0,0 +1 @@ +- The AGENTS.md injection cap defaults to 32 KiB (was 8 KiB), so a 13 KB AGENTS.md now reaches agents in full; set `repos..agents_md_max_bytes` to override it per repo (hard ceiling 256 KiB) or `HIVE_AGENTS_MD_MAX_BYTES` for the default, the truncation warning is logged once per file change, and `/api/status` repos report each repo's AGENTS.md size and any dropped sections. diff --git a/src/crux/agentsmd/agentsmd.go b/src/crux/agentsmd/agentsmd.go index b1c85d3fd7..4a0707202c 100644 --- a/src/crux/agentsmd/agentsmd.go +++ b/src/crux/agentsmd/agentsmd.go @@ -48,6 +48,7 @@ import ( "log/slog" "os" "path/filepath" + "strconv" "strings" "unicode/utf8" @@ -333,10 +334,10 @@ func (c *AgentsConfig) Resolve(names []string) string { // block ready to prepend to an agent kick. requestedSkills are the skills the // caller wants included; when nil, the config's own RequestedSkills (from // front-matter) are used. Returns "" when there is nothing to inject. The -// block is bounded to DefaultMaxInjectionBytes; see Render for the cap -// contract and for a configurable cap. +// block is bounded to the default cap (DefaultMaxBytes); see Render for the +// cap contract and for a configurable cap. func (c *AgentsConfig) InjectionText(requestedSkills []string) string { - out, _ := c.Render(requestedSkills, DefaultMaxInjectionBytes) + out, _ := c.Render(requestedSkills, 0) return out } @@ -346,10 +347,20 @@ func (c *AgentsConfig) InjectionText(requestedSkills []string) string { // says so where the agent will read it, naming the sections, so the agent // knows to open the file itself and the repo owner knows to shorten it. const ( - // DefaultMaxInjectionBytes caps the rendered AGENTS.md block when no - // project.agents_md_max_bytes is configured. It matches the skills cap - // (scheduler maxSkillsInjectionBytes), which is the model this follows. - DefaultMaxInjectionBytes = 8192 + // DefaultMaxInjectionBytes caps the rendered AGENTS.md block when neither + // repos..agents_md_max_bytes nor project.agents_md_max_bytes is + // configured and MaxBytesEnv is unset. It was 8192 until #18495; real + // repositories' files outgrew that (a 13 KB AGENTS.md lost whole + // sections), so the default now holds a large file in full. + DefaultMaxInjectionBytes = 32 * 1024 + // MaxInjectionBytesCeiling is the hard ceiling every cap is lowered to, + // whatever its source (per-repo, project, env), so one misconfigured + // repo cannot crowd the rest of the kick out of the model's context. + MaxInjectionBytesCeiling = 256 * 1024 + // MaxBytesEnv overrides DefaultMaxInjectionBytes hive-wide, for operators + // who set defaults by environment (hosted spokes). A value that is not a + // positive integer is ignored. Config keys still win over it. + MaxBytesEnv = "HIVE_AGENTS_MD_MAX_BYTES" // minInjectionBytes is the floor a configured cap is raised to: the header, // precedence sentence and warning reserve alone take ~1 KiB, so anything // lower could never carry a rule. @@ -462,14 +473,33 @@ func (c *AgentsConfig) skillSections(names []string) []injectionSection { return out } -// injectionMaxBytes applies the default and floor to a configured cap. +// DefaultMaxBytes is the cap that applies when no config key sets one: +// MaxBytesEnv when it holds a positive integer, else DefaultMaxInjectionBytes. +func DefaultMaxBytes() int { + if v := strings.TrimSpace(os.Getenv(MaxBytesEnv)); v != "" { + if n, err := strconv.Atoi(v); err == nil && n > 0 { + return n + } + } + return DefaultMaxInjectionBytes +} + +// EffectiveMaxBytes is the cap Render applies for a configured value n: the +// default (DefaultMaxBytes) when n is zero or negative, raised to the floor +// and lowered to MaxInjectionBytesCeiling. +func EffectiveMaxBytes(n int) int { return injectionMaxBytes(n) } + +// injectionMaxBytes applies the default, floor and ceiling to a configured cap. func injectionMaxBytes(n int) int { if n <= 0 { - n = DefaultMaxInjectionBytes + n = DefaultMaxBytes() } if n < minInjectionBytes { n = minInjectionBytes } + if n > MaxInjectionBytesCeiling { + n = MaxInjectionBytesCeiling + } return n } @@ -508,8 +538,8 @@ func injectionWarning(capBytes int, o InjectionOmitted) string { return b.String() } -// Render is InjectionText bounded to maxBytes (DefaultMaxInjectionBytes when -// zero, never below minInjectionBytes). The header and precedence statement +// Render is InjectionText bounded to maxBytes (DefaultMaxBytes when zero, +// never below minInjectionBytes nor above MaxInjectionBytesCeiling). The header and precedence statement // always render. Body sections (split at "#"/"##" headings) and then resolved // skills are visited in document order and each is kept only if it fits the // remaining budget whole; one that does not fit is dropped whole and later, diff --git a/src/crux/agentsmd/injection_cap_test.go b/src/crux/agentsmd/injection_cap_test.go index 74da92727f..c5366ad494 100644 --- a/src/crux/agentsmd/injection_cap_test.go +++ b/src/crux/agentsmd/injection_cap_test.go @@ -177,9 +177,73 @@ func TestInjectionMaxBytesDefaultsAndFloor(t *testing.T) { if got := injectionMaxBytes(10); got != minInjectionBytes { t.Errorf("tiny -> %d, want floor %d", got, minInjectionBytes) } - if got := injectionMaxBytes(32768); got != 32768 { + if got := injectionMaxBytes(16384); got != 16384 { t.Errorf("configured not honoured: %d", got) } + if got := injectionMaxBytes(MaxInjectionBytesCeiling * 4); got != MaxInjectionBytesCeiling { + t.Errorf("huge -> %d, want ceiling %d", got, MaxInjectionBytesCeiling) + } + if got := EffectiveMaxBytes(0); got != DefaultMaxInjectionBytes { + t.Errorf("EffectiveMaxBytes(0) = %d, want %d", got, DefaultMaxInjectionBytes) + } +} + +// #18495: the default is 32 KiB, so a 13 KB AGENTS.md (the real file that +// lost sections under the old 8 KiB cap) is injected in full with no warning. +func TestRender_ThirteenKBFileIsIncludedInFullByDefault(t *testing.T) { + t.Setenv(MaxBytesEnv, "") + if DefaultMaxInjectionBytes != 32*1024 { + t.Fatalf("default cap = %d, want 32 KiB", DefaultMaxInjectionBytes) + } + var body strings.Builder + for i := 0; body.Len() < 13*1000; i++ { + body.WriteString(section("Rule "+strconv.Itoa(i), 900)) + } + out, omitted := cfg(body.String()).Render(nil, 0) + if omitted.Any() || strings.Contains(out, InjectionTruncatedMarker) { + t.Fatalf("13 KB file must not be truncated by default: %+v", omitted) + } + for _, sec := range splitBodySections(body.String()) { + if !strings.Contains(out, sec.text) { + t.Fatalf("section %q missing from the default render", sec.name) + } + } +} + +func TestDefaultMaxBytesEnvOverride(t *testing.T) { + t.Setenv(MaxBytesEnv, "65536") + if got := DefaultMaxBytes(); got != 65536 { + t.Errorf("env default = %d, want 65536", got) + } + if got := EffectiveMaxBytes(0); got != 65536 { + t.Errorf("EffectiveMaxBytes(0) with env = %d, want 65536", got) + } + // A configured cap still wins over the env default. + if got := EffectiveMaxBytes(4096); got != 4096 { + t.Errorf("configured cap with env = %d, want 4096", got) + } + // The env value is still bounded by the ceiling. + t.Setenv(MaxBytesEnv, strconv.Itoa(MaxInjectionBytesCeiling*2)) + if got := EffectiveMaxBytes(0); got != MaxInjectionBytesCeiling { + t.Errorf("env above ceiling = %d, want %d", got, MaxInjectionBytesCeiling) + } + for _, bad := range []string{"abc", "-5", "0", " "} { + t.Setenv(MaxBytesEnv, bad) + if got := DefaultMaxBytes(); got != DefaultMaxInjectionBytes { + t.Errorf("env %q -> %d, want the built-in default", bad, got) + } + } +} + +func TestRender_EnvDefaultCapsWhenNothingConfigured(t *testing.T) { + t.Setenv(MaxBytesEnv, "2048") + out, omitted := cfg(section("Small", 100)+section("Big", 3000)).Render(nil, 0) + if len(omitted.Sections) != 1 || omitted.Sections[0] != "Big" { + t.Fatalf("env cap should drop the big section: %+v", omitted) + } + if !strings.Contains(out, InjectionTruncatedMarker+" 2048 bytes") { + t.Errorf("warning should name the env cap:\n%s", out) + } } func TestPrecedenceStatementIsOneSentence(t *testing.T) { diff --git a/src/crux/agentsmd/status.go b/src/crux/agentsmd/status.go new file mode 100644 index 0000000000..8039fd022a --- /dev/null +++ b/src/crux/agentsmd/status.go @@ -0,0 +1,70 @@ +package agentsmd + +import ( + "strings" + "sync" + "time" +) + +// InjectionStatus is what the last kick did with one repository's AGENTS.md +// (hivecommons/hive#18495): how big the file was, the cap that applied, how +// much of it reached the kick, and what was dropped. The scheduler records it +// on every render and the dashboard repo status reads it, so a truncated +// AGENTS.md is visible to the operator without reading logs. +type InjectionStatus struct { + // SourceBytes is the size of the AGENTS.md file that was read. + SourceBytes int `json:"sourceBytes"` + // RenderedBytes is the size of the block prepended to the kick. + RenderedBytes int `json:"renderedBytes"` + // CapBytes is the effective cap (after default, floor and ceiling). + CapBytes int `json:"capBytes"` + // Truncated is true when any section was dropped. + Truncated bool `json:"truncated"` + // WholeFile is true when nothing of the repository's text fit. + WholeFile bool `json:"wholeFile,omitempty"` + // OmittedSections names the dropped sections in document order. + OmittedSections []string `json:"omittedSections,omitempty"` + // OmittedBytes is the rendered size of what was dropped. + OmittedBytes int `json:"omittedBytes,omitempty"` + // UpdatedAt (RFC 3339, UTC) is when the status was recorded. + UpdatedAt string `json:"updatedAt"` +} + +var ( + statusMu sync.RWMutex + statuses = map[string]InjectionStatus{} +) + +func statusKey(repo string) string { return strings.ToLower(strings.TrimSpace(repo)) } + +// RecordStatus stores repo's latest injection status, keyed case-insensitively +// by repo ("owner/repo" by convention). A blank repo is ignored. +func RecordStatus(repo string, st InjectionStatus) { + key := statusKey(repo) + if key == "" { + return + } + if st.UpdatedAt == "" { + st.UpdatedAt = time.Now().UTC().Format(time.RFC3339) + } + st.OmittedSections = append([]string(nil), st.OmittedSections...) + statusMu.Lock() + statuses[key] = st + statusMu.Unlock() +} + +// StatusFor returns repo's latest recorded injection status, and whether one +// exists. A repo whose kicks never read an AGENTS.md has none. +func StatusFor(repo string) (InjectionStatus, bool) { + key := statusKey(repo) + if key == "" { + return InjectionStatus{}, false + } + statusMu.RLock() + st, ok := statuses[key] + statusMu.RUnlock() + if ok { + st.OmittedSections = append([]string(nil), st.OmittedSections...) + } + return st, ok +} diff --git a/src/crux/agentsmd/status_test.go b/src/crux/agentsmd/status_test.go new file mode 100644 index 0000000000..4e4357809f --- /dev/null +++ b/src/crux/agentsmd/status_test.go @@ -0,0 +1,54 @@ +package agentsmd + +import "testing" + +func resetStatuses() { + statusMu.Lock() + statuses = map[string]InjectionStatus{} + statusMu.Unlock() +} + +func TestRecordStatusRoundTripsCaseInsensitively(t *testing.T) { + resetStatuses() + t.Cleanup(resetStatuses) + sections := []string{"Style guide"} + RecordStatus("Acme/Widgets", InjectionStatus{ + SourceBytes: 40000, RenderedBytes: 30000, CapBytes: 32768, + Truncated: true, OmittedSections: sections, OmittedBytes: 9000, + }) + sections[0] = "mutated" + st, ok := StatusFor("acme/widgets") + if !ok { + t.Fatal("status not found by case-folded key") + } + if !st.Truncated || st.CapBytes != 32768 || st.SourceBytes != 40000 || st.RenderedBytes != 30000 || st.OmittedBytes != 9000 { + t.Errorf("status round-trip lost fields: %+v", st) + } + if len(st.OmittedSections) != 1 || st.OmittedSections[0] != "Style guide" { + t.Errorf("recorded sections must be copied, got %v", st.OmittedSections) + } + if st.UpdatedAt == "" { + t.Error("UpdatedAt should be stamped") + } + st.OmittedSections[0] = "changed by reader" + again, _ := StatusFor("ACME/WIDGETS") + if again.OmittedSections[0] != "Style guide" { + t.Errorf("reader mutation leaked into the registry: %v", again.OmittedSections) + } +} + +func TestRecordStatusIgnoresBlankRepo(t *testing.T) { + resetStatuses() + t.Cleanup(resetStatuses) + RecordStatus(" ", InjectionStatus{CapBytes: 1}) + if _, ok := StatusFor(""); ok { + t.Error("blank repo must not be recorded or found") + } + if _, ok := StatusFor("acme/none"); ok { + t.Error("unknown repo must not be found") + } + RecordStatus("acme/kept", InjectionStatus{UpdatedAt: "2026-01-01T00:00:00Z"}) + if st, _ := StatusFor("acme/kept"); st.UpdatedAt != "2026-01-01T00:00:00Z" { + t.Errorf("explicit UpdatedAt overwritten: %q", st.UpdatedAt) + } +} diff --git a/src/docs/agent-knowledge-and-memory.md b/src/docs/agent-knowledge-and-memory.md index e3527ebf04..71dd452daa 100644 --- a/src/docs/agent-knowledge-and-memory.md +++ b/src/docs/agent-knowledge-and-memory.md @@ -97,7 +97,7 @@ missing dir, non-GitHub forge or absent client skips with a DEBUG line. | Block | Cap | Config | |---|---|---| | `# Relevant Knowledge` | 25 facts, 8192 bytes (floor 512) | `knowledge.primer.max_facts`, `knowledge.primer.max_bytes` | -| Repo `AGENTS.md` | 8192 bytes (floor 2048), whole sections | `project.agents_md_max_bytes` (`agentsmd.DefaultMaxInjectionBytes`) | +| Repo `AGENTS.md` | 32768 bytes (floor 2048, ceiling 262144), whole sections | `repos..agents_md_max_bytes`, `project.agents_md_max_bytes`, env `HIVE_AGENTS_MD_MAX_BYTES` (`agentsmd.DefaultMaxInjectionBytes`) | | Declared skills | 8192 bytes, whole skills | `maxSkillsInjectionBytes` in `kick_priming.go` (fixed) | **Switches.** `knowledge.enabled` gates the primer only — the bead synthesizer diff --git a/src/docs/agents-md.md b/src/docs/agents-md.md index 1875970174..14d0ea7477 100644 --- a/src/docs/agents-md.md +++ b/src/docs/agents-md.md @@ -124,10 +124,28 @@ never appears with no rules under it. ### Size cap: whole sections, visible warning -The block is capped at `project.agents_md_max_bytes` bytes (default **8192** -— the same as the skills cap — minimum 2048; -[#12129](https://github.com/hivecommons/hive/issues/12129)). `AGENTS.md` is a -repo-owned contract, so the cap **never clips a rule mid-sentence**: +The block is capped at **32768 bytes (32 KiB)** by default, minimum 2048, hard +ceiling 262144 (256 KiB) +([#12129](https://github.com/hivecommons/hive/issues/12129), +[#18495](https://github.com/hivecommons/hive/issues/18495)). The default was +8192 until #18495: real repositories outgrew it (a 13 KB `AGENTS.md` lost whole +sections on every kick), so a file of that size is now included in full. The +cap that applies to a repo is resolved in this order: + +1. `repos..agents_md_max_bytes` — a per-repo override. `` is the + bare name from `project.repos` or `owner/repo`, matched case-insensitively. +2. `project.agents_md_max_bytes` — the hive-wide value. +3. The `HIVE_AGENTS_MD_MAX_BYTES` environment variable — the default for + operators who configure by environment (hosted spokes). A value that is not + a positive integer is ignored. +4. The built-in default, 32768 (`agentsmd.DefaultMaxInjectionBytes`). + +Whatever the source, the value is raised to the 2048 floor and lowered to the +256 KiB ceiling (`agentsmd.MaxInjectionBytesCeiling`), so one misconfigured repo +cannot crowd the rest of the kick out of the model's context. + +`AGENTS.md` is a repo-owned contract, so the cap **never clips a rule +mid-sentence**: - The body is split at its `#` and `##` headings (text before the first heading is the "(preamble)"; deeper headings and fenced code stay inside @@ -143,20 +161,35 @@ When anything was dropped, a one-line warning follows the precedence statement and precedes the surviving rules, so the agent reads it first: ``` -> ⚠️ AGENTS.md exceeded 8192 bytes; 2 section(s) omitted (9114 bytes): "Style guide", "skill: release-notes" — read AGENTS.md in the repository root for the full instructions before you start. +> ⚠️ AGENTS.md exceeded 32768 bytes; 2 section(s) omitted (9114 bytes): "Style guide", "skill: release-notes" — read AGENTS.md in the repository root for the full instructions before you start. ``` The scheduler logs the same facts at warn (`agentsmd: AGENTS.md exceeded the injection cap; sections dropped whole`, with `cap_bytes`, `omitted_sections`, `omitted_bytes`, `whole_file`) so the repo owner learns the file outgrew the cap from the log, not from an agent that -missed a rule. The fix on the repo side is to shorten `AGENTS.md` or move -reference material to a linked file; on the hive side, raise the cap: +missed a rule. The warning is logged **once per change** — the first kick that +sees a given file content and cap logs it, later kicks with the same file stay +quiet until the file or the cap changes — while the in-prompt warning line is +on every truncated kick. + +The same facts are on the dashboard repo status: each entry in the `/api/status` +payload's `repos` list carries an `agentsMd` object once a kick has read that +repo's `AGENTS.md`, with `sourceBytes` (file size), `capBytes` (effective cap), +`renderedBytes` (what reached the kick), `truncated`, `wholeFile`, +`omittedSections`, `omittedBytes` and `updatedAt`. It is absent for a repo no +kick has read a file for. + +The fix on the repo side is to shorten `AGENTS.md` or move reference material to +a linked file; on the hive side, raise the cap hive-wide or for one repo: ```yaml project: checkouts_dir: /data/checkouts - agents_md_max_bytes: 16384 # 0 = default 8192; values under 2048 are raised + agents_md_max_bytes: 16384 # 0 = default 32768; clamped to 2048..262144 +repos: + big-docs-repo: + agents_md_max_bytes: 65536 # this repo only; 0 inherits project ``` ### The precedence statement diff --git a/src/docs/api-reference/auth.md b/src/docs/api-reference/auth.md index 856dda33bd..08162df0b8 100644 --- a/src/docs/api-reference/auth.md +++ b/src/docs/api-reference/auth.md @@ -24,9 +24,9 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1782` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1783` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1784` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1787` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1788` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1789` | | `GET` | `/api/github-owner-identity` | Owner only | The hive owner's GitHub identity for remote repos ([#18197](https://github.com/hivecommons/hive/issues/18197)): `connected`, `login`, `scope`, `connected_at`, `usable`, `reason`, `verified_at`, `scope_required` (`public_repo`), `private_repos_supported` (false) and `file` (the token file path on the spoke). Never the token | `pkg/dashboard/api.go:555` | | `POST` | `/api/github-owner-identity/start` | Owner only | Start the consent: a GitHub device flow with the spoke's `oauth_client_id` asking for `public_repo`, separate from the scope-free login flow. Returns `user_code`, `verification_uri`, `expires_in`, `interval`, `scope` and the `flow_id` the poll must present. 502 when GitHub refused the device-code request | `pkg/dashboard/api.go:556` | | `POST` | `/api/github-owner-identity/poll` | Owner only | Poll the consent with `{"flow_id"}`: `status` `pending` / `slow_down` (poll again), `complete` (with `login` and the identity) or `error`. On completion the granted scope must cover `public_repo`, the token must validate and the account must be the logged-in owner's; the identity is then stored on the spoke (`/data/secrets/github-owner-token`, `HIVE_GITHUB_OWNER_TOKEN_FILE` overrides) and the reference-repo policies re-resolve. 400 without a live flow or with the wrong `flow_id`; audited as `github_owner_identity_connected` / `_rejected` | `pkg/dashboard/api.go:557` | diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index cb60b598a0..38eca5ce98 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -84,7 +84,7 @@ The monitor renders CI and Review concurrently on one shared PR row; see | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:377` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:378` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:379` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1789` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1794` | ### Activity observation provenance The CI snapshot retains real check/node IDs, head, App ID and transition times. diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index c15ccd85bf..f384f2e2ea 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -24,17 +24,17 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)). Also `startedAt` (RFC3339 process start — changes on every pod roll even when the build does not, so the dashboard can say "Restarted" vs "Upgraded") and, until the first status is published, `startupPhase`/`startupPhaseLabel` (the boot phase a fresh pod is in) ([#15788](https://github.com/hivecommons/hive/issues/15788)) | `pkg/dashboard/api.go:45` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=&to=` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:46` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:70` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1762` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1763` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1764` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1770` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1775` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1776` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1777` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1778` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1779` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1780` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1781` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1767` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1768` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1769` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1775` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced, dayUSD, weekUSD, monthUSD, windowsPriced}` is the governor strip's rotating `running N · $X this hour / today / this week / this month` figure (#15614) — the hour is the rise since the top of the clock hour, the wider windows are the daily cost ledger summed from 00:00 UTC today, Monday 00:00 UTC (ISO week) and the 1st 00:00 UTC plus the rise since the ledger's last snapshot, `windowsPriced:false` when there is no ledger yet; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376); `ci_failure_signals` `{count, last, kicks, unmatched}` is the webhook CI-failure signal store — distinct red (repo, head, check) signals retained, the most recent one `{repo, number, head_sha, check, conclusion, details_url, agent, at}`, webhook-triggered kicks/nudges since boot, and failure deliveries whose head matched no open PR; `workflow_approvals` `{approved, denied, permission_errors, last}` counts the hive's approvals of GitHub-gated workflow runs since boot (#16603) — runs approved, runs refused by the trust policy (once per head), `403`/`404` refusals for want of `actions: write`, and the most recent decision `{repo, number, head, run_id, outcome, at}`; `hotspots` `{count, actionable, filed}` is the merge-hotspot advisor's one-line summary (files at/above the thresholds, those with a split recommendation, those with a modularize issue filed), absent when the advisor is not wired — details on `GET /api/hotspots`; `writeback.dedupe` `{enabled, dedupe_same_item, dedupe_burst, rate_capped, hourly_cap, burst_items, burst_window_s, same_item_ttl_s}` is the write-back gate's content layer — the effective `writeback.dedupe.*` settings and the last-hour counts of writes held as `duplicate`, `burst` and `rate-capped` (each also listed under `GET /api/writeback/suppressed`); `referenceRepos[]` `{full, tier, reference_tier}` lists `project.reference_repos` apart from `repos[]` — `reference_tier` is `read-only`, `issues`, `prs` or `issues+prs` (`tier` is the same value, kept for older clients) and an entry carries no ACMM, work-item or pause fields, since a reference repo is studied, not worked (#18021); `config.gate_regressions[]` `{gate, previous, effective, source}` is the boot-time safety-gate regression list (#16438) — gates a previous runtime overlay on the PVC carried that the running config lacks or loosens (`review.require_labels`, `project.issue_filter.require_labels`, `project.paused_repos[]`, `writeback.per_repo[].mode`), empty on a healthy boot | `pkg/dashboard/server.go:1780` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1781` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1782` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1783` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1784` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1785` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1786` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | diff --git a/src/docs/api-reference/snapshots-and-style.md b/src/docs/api-reference/snapshots-and-style.md index 43abac7a2d..3a7beea1b1 100644 --- a/src/docs/api-reference/snapshots-and-style.md +++ b/src/docs/api-reference/snapshots-and-style.md @@ -6,7 +6,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/style` | Public | Sanitized custom dashboard CSS | `pkg/dashboard/api.go:47` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1852` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](../branding.md)) | `pkg/dashboard/server.go:1857` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:83` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:84` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:85` | diff --git a/src/docs/operator-reference/README.md b/src/docs/operator-reference/README.md index ed2ce03b4b..ca55cd255b 100644 --- a/src/docs/operator-reference/README.md +++ b/src/docs/operator-reference/README.md @@ -293,7 +293,7 @@ Go callers keep reading `cfg.Agents`, `cfg.Governor.Gateways` and so on through | `governor.merge_train_stall_warn_s` | `3600` seconds; `0` disables | **Settings → Auto-merge → Merge train → Stall warning after.** How long the head of a merge train may sit in one stage before the Activity Monitor reads the train **stalled** — the queued chip turns to "Merge queue · stalled — waiting on #15253 (waiting for CI) · 3h", the Merge queue popover marks the train, and the activity log records one `merge train stalled` line per train per hour naming the head, its state and how long. A soaking head is on its clock, not stalled, until that clock itself overruns the window ([#15395](https://github.com/hivecommons/hive/issues/15395)). | | `governor.trajectory.enabled` | Defaults to enabled. | The lane no-ops until a reviewer endpoint and model resolve from `governor.trajectory` or `governor.litellm`. | | `governor.kick_limits.max_issues` / `max_prs` | `100` / `50` | Caps on every issue list and every PR list (actionable, stale drafts, merge-eligible, CI-failing) rendered into a kick prompt; a cut list ends with an explicit "… and N more" line. An absent key or a negative value means the default; an explicit `0` opts out of the cap entirely (`KickListUnlimited` — every item is listed), and anything above `500` is pinned to `500`. Editable without touching this file under **Settings → Repos → Kick prompt list caps**. Truncation drops the *newest, lowest-priority* items: issues are listed oldest first, and PRs in review-priority order (fixes, then refactors/docs, then tests, oldest first within each class), so lowering a cap never hides the most urgent work. Raise `max_prs` only if your agents actually work more than 50 PRs per turn; the tail of a long list costs tokens and delivery time on every kick without changing behaviour (#7368). | -| `project.agents_md_max_bytes` | `8192`; values under `2048` are raised to `2048`. | Caps the repo `AGENTS.md` block prepended to a kick. Whole sections (split at `#`/`##` headings; each resolved skill is its own unit) are kept or dropped, never clipped mid-rule; when any are dropped the kick carries a one-line `⚠️ AGENTS.md exceeded N bytes; … — read AGENTS.md …` warning naming them and the scheduler logs it. See [agents-md.md](../agents-md.md#size-cap-whole-sections-visible-warning). | +| `project.agents_md_max_bytes` | `32768` (or env `HIVE_AGENTS_MD_MAX_BYTES`); clamped to `2048`..`262144`. `repos..agents_md_max_bytes` overrides it per repo. | Caps the repo `AGENTS.md` block prepended to a kick. Whole sections (split at `#`/`##` headings; each resolved skill is its own unit) are kept or dropped, never clipped mid-rule; when any are dropped the kick carries a one-line `⚠️ AGENTS.md exceeded N bytes; … — read AGENTS.md …` warning naming them and the scheduler logs it. See [agents-md.md](../agents-md.md#size-cap-whole-sections-visible-warning). | | `project.style` | unset (built-in text applies) | Hive-wide **house style**: a short how-to-change rule list prepended to every kick on every backend, directly under the header. A managed repo's root `HIVE_STYLE.md` (read from `project.checkouts_dir`) overrides it; precedence repo > hive > built-in. Inline text wins over `project.style_file`. See [house-style.md](../house-style.md). | | `project.style_file` | unset | Path on the hive host holding the hive-wide house style; used when `project.style` is empty. | | `project.style_max_bytes` | `4096`; values under `512` are raised to `512`. | Caps each house-style candidate. An oversize candidate is skipped whole (not clipped) and the next source applies; the skip is audited as `house_style_skip`. The repo file is also run through ioscan at the issue-body policy and refused whole on a block. | diff --git a/src/internal/testutil/dashboard_import_allowlist.txt b/src/internal/testutil/dashboard_import_allowlist.txt index 8b11ddd10a..61aff277d9 100644 --- a/src/internal/testutil/dashboard_import_allowlist.txt +++ b/src/internal/testutil/dashboard_import_allowlist.txt @@ -9,7 +9,9 @@ # deleted so the ratchet tightens. Entries are sorted. # workflowmodel: /api/workflows handlers compile lifecycle models (Compile, Profile diagnostics) and the tracker emits per-repo workflow columns; the store and bindings already route through Dependencies (hivecommons/hive#17620 P2). # egressmark: deployment_upgrade.go dials the in-cluster Kubernetes API for the hive's own rollout; the dial must carry the forced-egress SO_MARK or nodes without xt_owner redirect it into the MITM proxy (hivecommons/hive#17817). +# agentsmd: the /api/status repo entries carry each repo's last AGENTS.md injection status (size, effective cap, dropped sections) from agentsmd.StatusFor, the read side of the registry the scheduler records into (hivecommons/hive#18495). github.com/hivecommons/hive/crux +github.com/hivecommons/hive/crux/agentsmd github.com/hivecommons/hive/crux/claude github.com/hivecommons/hive/crux/egressmark github.com/hivecommons/hive/crux/kubejob diff --git a/src/pkg/config/config.go b/src/pkg/config/config.go index 5b0950dfe5..e570d0e703 100644 --- a/src/pkg/config/config.go +++ b/src/pkg/config/config.go @@ -217,6 +217,10 @@ type Config struct { // UpstreamWatch declares per-repo upstreams and filters for the fork // upstream watch (hivecommons/hive#9966). Default off. UpstreamWatch UpstreamWatchConfig `yaml:"upstream_watch,omitempty" json:"upstream_watch,omitempty"` + // Repos holds per-repository overrides keyed by the bare name from + // project.repos or "owner/repo" (hivecommons/hive#18495). Absent means + // every repo inherits the hive-wide values. See RepoSettings. + Repos map[string]RepoSettings `yaml:"repos,omitempty" json:"repos,omitempty"` // Convergence toggles the convergence-driven admission surfaces // (kubestellar/hive#3845 follow-ons). Default off → zero behaviour change. Convergence ConvergenceConfig `yaml:"convergence,omitempty" json:"convergence,omitempty"` @@ -1151,8 +1155,10 @@ type ProjectConfig struct { // (#12129). The block is cut at heading boundaries — whole sections are // kept or dropped, never clipped mid-rule — and when anything is dropped // the kick carries a one-line warning naming the omitted sections and the - // scheduler logs it. Zero means the agentsmd default (8192); values below - // 2048 are raised to 2048. + // scheduler logs it. Zero means the agentsmd default (32768, or + // HIVE_AGENTS_MD_MAX_BYTES when set); values below 2048 are raised to + // 2048 and values above the 262144 hard ceiling are lowered to it. + // repos..agents_md_max_bytes overrides this per repo (#18495). AgentsMdMaxBytes int `yaml:"agents_md_max_bytes,omitempty"` // Style is the hive-wide house style: a short list of how-to-change rules diff --git a/src/pkg/config/repo_settings.go b/src/pkg/config/repo_settings.go new file mode 100644 index 0000000000..fa2a5f9dc7 --- /dev/null +++ b/src/pkg/config/repo_settings.go @@ -0,0 +1,49 @@ +package config + +import "strings" + +// RepoSettings is one managed repository's per-repo knobs under the top-level +// `repos:` map (hivecommons/hive#18495). It is additive: a repo with no entry +// inherits the hive-wide value of every knob, so an absent map is exactly the +// previous behaviour. +type RepoSettings struct { + // AgentsMdMaxBytes caps this repo's rendered AGENTS.md block, overriding + // project.agents_md_max_bytes. Zero inherits it. The agentsmd floor and + // hard ceiling still apply (agentsmd.EffectiveMaxBytes). + AgentsMdMaxBytes int `yaml:"agents_md_max_bytes,omitempty" json:"agents_md_max_bytes,omitempty"` +} + +// RepoSettingsFor returns repo's entry from the `repos:` map, and whether one +// exists. repo may be given bare or org-qualified, and a key may be written +// either way too: both sides are org-qualified and case-folded before they are +// compared, since GitHub repository names are case-insensitive. +func (c *Config) RepoSettingsFor(repo string) (RepoSettings, bool) { + if c == nil || len(c.Repos) == 0 || strings.TrimSpace(repo) == "" { + return RepoSettings{}, false + } + org := c.Project.Org + want := repoPauseKey(org, strings.TrimSpace(repo)) + if rs, ok := c.Repos[repo]; ok { + return rs, true + } + for key, rs := range c.Repos { + if repoPauseKey(org, strings.TrimSpace(key)) == want { + return rs, true + } + } + return RepoSettings{}, false +} + +// AgentsMdMaxBytesFor is the configured AGENTS.md injection cap for repo: +// repos..agents_md_max_bytes when set, else +// project.agents_md_max_bytes. Zero means "use the agentsmd default"; the +// floor and ceiling are applied by the agentsmd package, not here. +func (c *Config) AgentsMdMaxBytesFor(repo string) int { + if c == nil { + return 0 + } + if rs, ok := c.RepoSettingsFor(repo); ok && rs.AgentsMdMaxBytes > 0 { + return rs.AgentsMdMaxBytes + } + return c.Project.AgentsMdMaxBytes +} diff --git a/src/pkg/config/repo_settings_test.go b/src/pkg/config/repo_settings_test.go new file mode 100644 index 0000000000..245f098881 --- /dev/null +++ b/src/pkg/config/repo_settings_test.go @@ -0,0 +1,52 @@ +package config + +import ( + "testing" + + "gopkg.in/yaml.v3" +) + +func TestAgentsMdMaxBytesFor(t *testing.T) { + c := &Config{ + Project: ProjectConfig{Org: "acme", AgentsMdMaxBytes: 16384}, + Repos: map[string]RepoSettings{ + "widgets": {AgentsMdMaxBytes: 65536}, + "Other/Gadget": {AgentsMdMaxBytes: 4096}, + "inherits": {}, + }, + } + cases := map[string]int{ + "widgets": 65536, // bare key, bare lookup + "acme/widgets": 65536, // bare key, qualified lookup + "ACME/Widgets": 65536, // case-folded + "other/gadget": 4096, // qualified key + "inherits": 16384, // entry without the knob inherits project + "unlisted": 16384, // no entry inherits project + } + for repo, want := range cases { + if got := c.AgentsMdMaxBytesFor(repo); got != want { + t.Errorf("AgentsMdMaxBytesFor(%q) = %d, want %d", repo, got, want) + } + } + if got := c.AgentsMdMaxBytesFor(""); got != 16384 { + t.Errorf("blank repo = %d, want project value", got) + } + var nilCfg *Config + if got := nilCfg.AgentsMdMaxBytesFor("widgets"); got != 0 { + t.Errorf("nil config = %d, want 0", got) + } + if _, ok := (&Config{}).RepoSettingsFor("widgets"); ok { + t.Error("empty repos map must report no entry") + } +} + +func TestReposAgentsMdMaxBytesYAML(t *testing.T) { + var c Config + src := "project:\n org: acme\n repos: [widgets]\nrepos:\n widgets:\n agents_md_max_bytes: 49152\n" + if err := yaml.Unmarshal([]byte(src), &c); err != nil { + t.Fatal(err) + } + if got := c.AgentsMdMaxBytesFor("widgets"); got != 49152 { + t.Errorf("yaml per-repo cap = %d, want 49152", got) + } +} diff --git a/src/pkg/dashboard/repo_agentsmd_status_test.go b/src/pkg/dashboard/repo_agentsmd_status_test.go new file mode 100644 index 0000000000..98e74bf9c4 --- /dev/null +++ b/src/pkg/dashboard/repo_agentsmd_status_test.go @@ -0,0 +1,30 @@ +package dashboard + +import ( + "testing" + + "github.com/hivecommons/hive/crux/agentsmd" + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/governor" +) + +// #18495: the repo status payload carries the last AGENTS.md injection +// status, so a truncated file is visible without reading logs. +func TestBuildReposCarriesAgentsMdStatus(t *testing.T) { + agentsmd.RecordStatus("acme18495/capped", agentsmd.InjectionStatus{ + SourceBytes: 50000, RenderedBytes: 32000, CapBytes: 32768, + Truncated: true, OmittedSections: []string{"Style guide"}, OmittedBytes: 18000, + }) + cfg := &config.Config{Project: config.ProjectConfig{Org: "acme18495", Repos: []string{"capped", "unread"}}} + repos := buildRepos(cfg, nil, governor.State{}) + if len(repos) != 2 { + t.Fatalf("got %d repos, want 2", len(repos)) + } + got := repos[0].AgentsMd + if got == nil || !got.Truncated || got.CapBytes != 32768 || got.SourceBytes != 50000 || len(got.OmittedSections) != 1 { + t.Errorf("capped repo status wrong: %+v", got) + } + if repos[1].AgentsMd != nil { + t.Errorf("repo without a recorded injection should carry no status: %+v", repos[1].AgentsMd) + } +} diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go index 1b90df260a..f86b9265dd 100644 --- a/src/pkg/dashboard/server.go +++ b/src/pkg/dashboard/server.go @@ -22,6 +22,7 @@ import ( "time" "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/watchdog" "github.com/hivecommons/hive/pkg/acmmadvisor" "github.com/hivecommons/hive/pkg/compliance" @@ -1390,6 +1391,10 @@ type FrontendRepo struct { // from /api/config. Forge string `json:"forge"` ForgeURL string `json:"forgeUrl,omitempty"` + // AgentsMd is what the last kick did with this repo's AGENTS.md + // (hivecommons/hive#18495): file size, effective cap, injected size and + // any sections dropped by the cap. Nil until a kick has read the file. + AgentsMd *agentsmd.InjectionStatus `json:"agentsMd,omitempty"` } type FrontendBeads struct { diff --git a/src/pkg/dashboard/settings_parity_allowlist.txt b/src/pkg/dashboard/settings_parity_allowlist.txt index 566fd37f74..c3de112839 100644 --- a/src/pkg/dashboard/settings_parity_allowlist.txt +++ b/src/pkg/dashboard/settings_parity_allowlist.txt @@ -511,6 +511,7 @@ project.repo_policies[].self_authorization_hold # TODO #11854 project.repos[] # TODO #11854 providers.status.enabled # TODO #11854 removed_agents[] # TODO #11854 +repos..agents_md_max_bytes # TODO #18495 (per-repo AGENTS.md cap; Settings control pending) review.backlog.labels[] # TODO #11854 review.bot_author_full_review_paths[] # TODO #14625 review.bot_author_model # TODO #14625 diff --git a/src/pkg/dashboard/status_builder.go b/src/pkg/dashboard/status_builder.go index fcfa8737e6..9d5bcdf3c4 100644 --- a/src/pkg/dashboard/status_builder.go +++ b/src/pkg/dashboard/status_builder.go @@ -16,6 +16,7 @@ import ( "time" "github.com/hivecommons/hive/crux" + "github.com/hivecommons/hive/crux/agentsmd" "github.com/hivecommons/hive/crux/paneclass" "github.com/hivecommons/hive/crux/skillreg" "github.com/hivecommons/hive/crux/watchdog" @@ -2556,6 +2557,9 @@ func buildReposWithForge(cfg *config.Config, actionable *github.ActionableResult } } } + if st, ok := agentsmd.StatusFor(full); ok { + r.AgentsMd = &st + } if actionable != nil && !r.Paused && !countsPresent { r.CountsIncomplete = true } diff --git a/src/pkg/scheduler/kick_priming.go b/src/pkg/scheduler/kick_priming.go index 51e4ad320d..29439287b0 100644 --- a/src/pkg/scheduler/kick_priming.go +++ b/src/pkg/scheduler/kick_priming.go @@ -2,8 +2,13 @@ package scheduler import ( "context" + "crypto/sha256" + "encoding/hex" "fmt" "log/slog" + "os" + "path/filepath" + "strconv" "strings" "github.com/hivecommons/hive/crux/agentsmd" @@ -86,7 +91,10 @@ func sameRepo(sourceRepo, org, repo string) bool { // primeAgentsMd reads the repository's AGENTS.md (the cross-tool convention for // per-repo agent instructions) plus its requested skills and returns text to // prepend to the kick. It is tolerant: a missing or malformed file yields "". -func (s *Scheduler) primeAgentsMd(repoRoot string) string { +// repo names the repository the root belongs to; it selects the per-repo cap +// (repos..agents_md_max_bytes) and keys the recorded injection status +// the dashboard reads (#18495). It may be "" (no per-repo cap, no status). +func (s *Scheduler) primeAgentsMd(repo, repoRoot string) string { if repoRoot == "" { return "" } @@ -96,7 +104,7 @@ func (s *Scheduler) primeAgentsMd(repoRoot string) string { s.logger.Warn("agentsmd: parse failed, skipping injection", "root", repoRoot, "error", err) return "" } - capBytes := s.agentsMdMaxBytes() + capBytes := s.agentsMdMaxBytes(repo) section, omitted := cfg.Render(nil, capBytes) if section == "" { // The silent half of kubestellar/hive#5227: a wired root holding no @@ -110,16 +118,26 @@ func (s *Scheduler) primeAgentsMd(repoRoot string) string { "requested_skills", len(cfg.RequestedSkills), "chars", len(section), ) - if omitted.Any() { + // capBytes 0 is the config "use default" sentinel; log and report the cap + // that applied so the operator can act on it (#17318). + effectiveCap := agentsmd.EffectiveMaxBytes(capBytes) + source, _ := os.ReadFile(filepath.Join(repoRoot, agentsmd.AgentsFileName)) + if qualified := s.agentsMdStatusRepo(repo); qualified != "" { + agentsmd.RecordStatus(qualified, agentsmd.InjectionStatus{ + SourceBytes: len(source), + RenderedBytes: len(section), + CapBytes: effectiveCap, + Truncated: omitted.Any(), + WholeFile: omitted.WholeFile, + OmittedSections: omitted.Sections, + OmittedBytes: omitted.Bytes, + }) + } + if omitted.Any() && s.agentsMdWarnOnce(repoRoot, effectiveCap, source) { // The kick carries its own warning line; this is the operator-side // half, so the repo owner learns the file outgrew the cap from the log - // rather than from an agent that missed a rule (#12129). - // capBytes 0 is the config "use default" sentinel; log the cap that - // applied so the operator can act on it (#17318). - effectiveCap := capBytes - if effectiveCap <= 0 { - effectiveCap = agentsmd.DefaultMaxInjectionBytes - } + // rather than from an agent that missed a rule (#12129). It is said + // once per file content and cap, not on every kick (#18495). s.logger.Warn("agentsmd: AGENTS.md exceeded the injection cap; sections dropped whole", "root", repoRoot, "cap_bytes", effectiveCap, "whole_file", omitted.WholeFile, "omitted_sections", omitted.Sections, "omitted_bytes", omitted.Bytes) @@ -127,13 +145,38 @@ func (s *Scheduler) primeAgentsMd(repoRoot string) string { return section } -// agentsMdMaxBytes is project.agents_md_max_bytes, or zero for the agentsmd -// default when no config is loaded. -func (s *Scheduler) agentsMdMaxBytes() int { +// agentsMdWarnOnce reports whether the truncation warning for root should be +// logged: true the first time a given file content and cap is seen, false on +// every later kick until either changes. +func (s *Scheduler) agentsMdWarnOnce(root string, capBytes int, source []byte) bool { + sum := sha256.Sum256(source) + fingerprint := hex.EncodeToString(sum[:]) + "|" + strconv.Itoa(capBytes) + prev, loaded := s.agentsMdWarned.Swap(root, fingerprint) + return !loaded || prev != fingerprint +} + +// agentsMdStatusRepo is the "owner/repo" key an injection status is recorded +// under, or "" when repo is blank. +func (s *Scheduler) agentsMdStatusRepo(repo string) string { + repo = strings.TrimSpace(repo) + if repo == "" { + return "" + } + org := "" + if s.cfg != nil { + org = s.cfg.Project.Org + } + return config.QualifyRepo(org, repo) +} + +// agentsMdMaxBytes is the configured AGENTS.md cap for repo +// (repos..agents_md_max_bytes, else project.agents_md_max_bytes), or +// zero for the agentsmd default when neither is set or no config is loaded. +func (s *Scheduler) agentsMdMaxBytes(repo string) int { if s.cfg == nil { return 0 } - return s.cfg.Project.AgentsMdMaxBytes + return s.cfg.AgentsMdMaxBytesFor(repo) } // skillsRegistryDir is the host-local directory the skill registry is loaded diff --git a/src/pkg/scheduler/kick_priming_agentsmd_cap_test.go b/src/pkg/scheduler/kick_priming_agentsmd_cap_test.go index 6423864da1..568f58189d 100644 --- a/src/pkg/scheduler/kick_priming_agentsmd_cap_test.go +++ b/src/pkg/scheduler/kick_priming_agentsmd_cap_test.go @@ -31,7 +31,7 @@ func TestPrimeAgentsMd_CapIsVisibleInKickAndLog(t *testing.T) { t.Fatal(err) } - got := s.primeAgentsMd(root) + got := s.primeAgentsMd("", root) if got == "" { t.Fatal("expected an injection") } @@ -71,7 +71,7 @@ func TestPrimeAgentsMd_UnderCapHasNoWarning(t *testing.T) { if err := os.WriteFile(filepath.Join(root, "AGENTS.md"), []byte("## Tests\n\nRun `make verify`.\n"), 0o644); err != nil { t.Fatal(err) } - got := s.primeAgentsMd(root) + got := s.primeAgentsMd("", root) if !strings.Contains(got, "Run `make verify`.") { t.Fatalf("body missing:\n%s", got) } @@ -95,7 +95,7 @@ func TestPrimeAgentsMd_LogsEffectiveCapForDefault(t *testing.T) { if err := os.WriteFile(filepath.Join(root, "AGENTS.md"), []byte(file), 0o644); err != nil { t.Fatal(err) } - s.primeAgentsMd(root) + s.primeAgentsMd("", root) log := logBuf.String() if !strings.Contains(log, "exceeded the injection cap") { t.Fatalf("expected the cap warning, got:\n%s", log) diff --git a/src/pkg/scheduler/kick_priming_agentsmd_repo_cap_test.go b/src/pkg/scheduler/kick_priming_agentsmd_repo_cap_test.go new file mode 100644 index 0000000000..10a871f9e1 --- /dev/null +++ b/src/pkg/scheduler/kick_priming_agentsmd_repo_cap_test.go @@ -0,0 +1,120 @@ +package scheduler + +import ( + "bytes" + "log/slog" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/hivecommons/hive/crux/agentsmd" + "github.com/hivecommons/hive/pkg/config" +) + +const agentsMdCapWarning = "AGENTS.md exceeded the injection cap" + +func writeAgentsMd(t *testing.T, root, body string) { + t.Helper() + if err := os.WriteFile(filepath.Join(root, agentsmd.AgentsFileName), []byte(body), 0o644); err != nil { + t.Fatal(err) + } +} + +func thirteenKBAgentsMd() string { + var b strings.Builder + for i := 0; b.Len() < 13*1000; i++ { + b.WriteString("## Rule " + string(rune('A'+i)) + "\n\n" + strings.Repeat("Follow the rule. ", 55) + "\n\n") + } + return b.String() +} + +// #18495: with nothing configured, a 13 KB AGENTS.md reaches the kick whole. +func TestPrimeAgentsMd_ThirteenKBIncludedInFullByDefault(t *testing.T) { + t.Setenv(agentsmd.MaxBytesEnv, "") + var logBuf bytes.Buffer + logger := slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug})) + s := New(&config.Config{Project: config.ProjectConfig{Org: "acme"}}, logger) + root := t.TempDir() + file := thirteenKBAgentsMd() + writeAgentsMd(t, root, file) + + got := s.primeAgentsMd("widgets13", root) + if strings.Contains(got, agentsmd.InjectionTruncatedMarker) || strings.Contains(logBuf.String(), agentsMdCapWarning) { + t.Fatalf("13 KB AGENTS.md was truncated by default:\n%s", logBuf.String()) + } + if !strings.Contains(got, strings.TrimSpace(file[strings.LastIndex(file, "## Rule"):])) { + t.Error("last section of the 13 KB file missing from the kick") + } + st, ok := agentsmd.StatusFor("acme/widgets13") + if !ok { + t.Fatal("injection status not recorded") + } + if st.Truncated || st.SourceBytes != len(file) || st.CapBytes != agentsmd.DefaultMaxInjectionBytes || st.RenderedBytes != len(got) { + t.Errorf("status wrong: %+v (file %d bytes)", st, len(file)) + } +} + +// A per-repo cap overrides the project cap for that repo only. +func TestPrimeAgentsMd_PerRepoOverride(t *testing.T) { + var logBuf bytes.Buffer + logger := slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug})) + cfg := &config.Config{ + Project: config.ProjectConfig{Org: "acme"}, + Repos: map[string]config.RepoSettings{"tight": {AgentsMdMaxBytes: 4096}}, + } + s := New(cfg, logger) + root := t.TempDir() + writeAgentsMd(t, root, thirteenKBAgentsMd()) + + got := s.primeAgentsMd("tight", root) + if len(got) > 4096 || !strings.Contains(got, agentsmd.InjectionTruncatedMarker+" 4096 bytes") { + t.Fatalf("per-repo cap not applied (%d bytes):\n%s", len(got), got) + } + st, ok := agentsmd.StatusFor("acme/tight") + if !ok || !st.Truncated || st.CapBytes != 4096 || len(st.OmittedSections) == 0 { + t.Errorf("truncation not reported in status: %+v", st) + } + // Another repo with the same file inherits the (default) project cap. + if other := s.primeAgentsMd("loose", root); strings.Contains(other, agentsmd.InjectionTruncatedMarker) { + t.Error("per-repo cap leaked into another repo") + } +} + +// The truncation warning is logged once per content change, not every kick. +func TestPrimeAgentsMd_WarnsOncePerContentChange(t *testing.T) { + var logBuf bytes.Buffer + logger := slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelDebug})) + s := New(&config.Config{Project: config.ProjectConfig{AgentsMdMaxBytes: 2048}}, logger) + root := t.TempDir() + big := "## Keep\n\nshort\n\n## Huge\n\n" + strings.Repeat("x", 3000) + "\n" + writeAgentsMd(t, root, big) + + for i := 0; i < 3; i++ { + if got := s.primeAgentsMd("", root); !strings.Contains(got, agentsmd.InjectionTruncatedMarker) { + t.Fatalf("kick %d lost its in-prompt warning", i) + } + } + if n := strings.Count(logBuf.String(), agentsMdCapWarning); n != 1 { + t.Fatalf("warning logged %d times for unchanged content, want 1", n) + } + writeAgentsMd(t, root, big+"\n## Huge too\n\n"+strings.Repeat("y", 3000)+"\n") + s.primeAgentsMd("", root) + s.primeAgentsMd("", root) + if n := strings.Count(logBuf.String(), agentsMdCapWarning); n != 2 { + t.Fatalf("warning logged %d times after one content change, want 2", n) + } +} + +func TestAgentsMdStatusRepoAndMaxBytesWithoutConfig(t *testing.T) { + s := &Scheduler{} + if got := s.agentsMdStatusRepo(" "); got != "" { + t.Errorf("blank repo -> %q", got) + } + if got := s.agentsMdStatusRepo("acme/x"); got != "acme/x" { + t.Errorf("qualified repo -> %q", got) + } + if got := s.agentsMdMaxBytes("x"); got != 0 { + t.Errorf("nil config cap = %d, want 0", got) + } +} diff --git a/src/pkg/scheduler/kick_priming_test.go b/src/pkg/scheduler/kick_priming_test.go index d90fc0d90b..e8095b3259 100644 --- a/src/pkg/scheduler/kick_priming_test.go +++ b/src/pkg/scheduler/kick_priming_test.go @@ -145,7 +145,7 @@ func TestAgentsRepoRoot_ThreadedRootReachesTheKick(t *testing.T) { cfg.Project.CheckoutsDir = checkouts s := New(cfg, slog.Default()) - got := s.primeAgentsMd(s.agentsRepoRoot(cfg.Project.PrimaryRepo)) + got := s.primeAgentsMd(cfg.Project.PrimaryRepo, s.agentsRepoRoot(cfg.Project.PrimaryRepo)) if !strings.Contains(got, body) { t.Fatalf("AGENTS.md body did not reach the injection; got %q", got) } @@ -155,15 +155,15 @@ func TestAgentsRepoRoot_ThreadedRootReachesTheKick(t *testing.T) { func TestPrimeAgentsMd_EmptyRootIsNoOp(t *testing.T) { s := New(&config.Config{}, slog.Default()) - if got := s.primeAgentsMd(""); got != "" { - t.Errorf("primeAgentsMd(\"\") = %q, want empty", got) + if got := s.primeAgentsMd("", ""); got != "" { + t.Errorf("primeAgentsMd(\"\", \"\") = %q, want empty", got) } } func TestPrimeAgentsMd_MissingFileYieldsEmpty(t *testing.T) { s := New(&config.Config{}, slog.Default()) root := t.TempDir() // no AGENTS.md inside - if got := s.primeAgentsMd(root); got != "" { + if got := s.primeAgentsMd("", root); got != "" { t.Errorf("primeAgentsMd(root without AGENTS.md) = %q, want empty", got) } } @@ -176,7 +176,7 @@ func TestPrimeAgentsMd_InjectsBody(t *testing.T) { t.Fatal(err) } - got := s.primeAgentsMd(root) + got := s.primeAgentsMd("", root) if got == "" { t.Fatal("primeAgentsMd returned empty for a root with AGENTS.md") } @@ -194,7 +194,7 @@ func TestPrimeAgentsMd_EmptyAgentsMdYieldsEmpty(t *testing.T) { if err := os.WriteFile(filepath.Join(root, "AGENTS.md"), []byte(" \n\n"), 0o644); err != nil { t.Fatal(err) } - if got := s.primeAgentsMd(root); got != "" { + if got := s.primeAgentsMd("", root); got != "" { t.Errorf("primeAgentsMd(blank AGENTS.md) = %q, want empty", got) } } @@ -253,7 +253,7 @@ func TestAgentsRepoRoot_FetchesFromGitHubWhenNoLocalRoot(t *testing.T) { if f.last != [4]string{"hivecommons", "hive", "AGENTS.md", ""} { t.Errorf("fetched %v, want owner/repo AGENTS.md at the default branch", f.last) } - if got := s.primeAgentsMd(root); !strings.Contains(got, body) { + if got := s.primeAgentsMd("", root); !strings.Contains(got, body) { t.Fatalf("fetched AGENTS.md did not reach the injection; got %q", got) } diff --git a/src/pkg/scheduler/scheduler.go b/src/pkg/scheduler/scheduler.go index 6bf62d3a8d..baab42979a 100644 --- a/src/pkg/scheduler/scheduler.go +++ b/src/pkg/scheduler/scheduler.go @@ -29,8 +29,11 @@ type Scheduler struct { agentsMdFetcher AgentsMdFetcher // remoteAgents caches the materialised AGENTS.md root per "owner/repo" // for the GitHub fallback in remoteAgentsRepoRoot (#17090). - remoteAgents map[string]remoteAgentsMd - remoteAgentsMu sync.Mutex + remoteAgents map[string]remoteAgentsMd + remoteAgentsMu sync.Mutex + // agentsMdWarned is root -> "|" last warned + // about, so a truncated file is logged once per change, not per kick. + agentsMdWarned sync.Map auditFunc AuditFunc advisoryFunc AdvisoryFunc classifierUnavailableFunc func(error) diff --git a/src/pkg/scheduler/templates.go b/src/pkg/scheduler/templates.go index 1d3ccefd11..8dc7d5ed94 100644 --- a/src/pkg/scheduler/templates.go +++ b/src/pkg/scheduler/templates.go @@ -355,7 +355,7 @@ 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. - agentsSection := s.primeAgentsMd(repoRoot) + agentsSection := s.primeAgentsMd(primaryRepo, repoRoot) if agentsSection != "" { knowledgeSection = agentsSection + "\n" + knowledgeSection }