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/changed-18495-agents-md-cap.md
Original file line number Diff line number Diff line change
@@ -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.<repo>.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.
52 changes: 41 additions & 11 deletions src/crux/agentsmd/agentsmd.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ import (
"log/slog"
"os"
"path/filepath"
"strconv"
"strings"
"unicode/utf8"

Expand Down Expand Up @@ -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
}

Expand All @@ -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.<repo>.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.
Expand Down Expand Up @@ -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
}

Expand Down Expand Up @@ -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,
Expand Down
66 changes: 65 additions & 1 deletion src/crux/agentsmd/injection_cap_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
70 changes: 70 additions & 0 deletions src/crux/agentsmd/status.go
Original file line number Diff line number Diff line change
@@ -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
}
54 changes: 54 additions & 0 deletions src/crux/agentsmd/status_test.go
Original file line number Diff line number Diff line change
@@ -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)
}
}
2 changes: 1 addition & 1 deletion src/docs/agent-knowledge-and-memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<repo>.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
Expand Down
49 changes: 41 additions & 8 deletions src/docs/agents-md.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<repo>.agents_md_max_bytes` — a per-repo override. `<repo>` 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
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions src/docs/api-reference/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
Loading
Loading