From 104419fb97905b9ead3b35040677f0a3d2af3ea0 Mon Sep 17 00:00:00 2001 From: Danathar Date: Fri, 6 Nov 2026 07:29:37 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20fix(adminmcp):=20the=20text=20ca?= =?UTF-8?q?p=20cuts=20the=20largest=20list,=20not=20the=20longest?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A result over the 256 KiB cap had its longest top-level list halved first, by entry count. A long list of small entries frees almost nothing, so on a 15-agent, 12-repo hive fleet_status (350 KB) lost half of acmmPackAgents, cadenceMatrix and configuredAgents for a few KB, besides the cuts to agents and repos that were needed. shrinkLists now ranks lists by encoded size and breaks ties by name, so small lists stay whole and one result is cut the same way on every call (ties were decided by map order). Co-Authored-By: Claude Fable 5.1 Signed-off-by: Danathar --- .../fixed-admin-mcp-text-cap-largest-list.md | 1 + src/docs/design/admin-mcp.md | 8 +- src/pkg/adminmcp/polish_test.go | 85 +++++++++++++++++++ src/pkg/adminmcp/result_cap.go | 47 ++++++++-- 4 files changed, 131 insertions(+), 10 deletions(-) create mode 100644 changelog.d/fixed-admin-mcp-text-cap-largest-list.md diff --git a/changelog.d/fixed-admin-mcp-text-cap-largest-list.md b/changelog.d/fixed-admin-mcp-text-cap-largest-list.md new file mode 100644 index 0000000000..89ed3d3e92 --- /dev/null +++ b/changelog.d/fixed-admin-mcp-text-cap-largest-list.md @@ -0,0 +1 @@ +- Admin MCP: a result over the 256 KiB text cap now loses entries only from the lists that are actually large. The cap halved the list with the most entries first, whatever its size, so on a 15-agent, 12-repo hive `fleet_status` (350 KB) came back with `acmmPackAgents`, `cadenceMatrix` and `configuredAgents` cut from 15 entries to 7 for a saving of a few KB, on top of the cuts to `agents` and `repos` that were needed. Lists are now ranked by encoded size, so small lists stay whole, and lists of equal size are cut in name order instead of at random, so the same result is truncated the same way on every call. diff --git a/src/docs/design/admin-mcp.md b/src/docs/design/admin-mcp.md index 220ec4b671..0b481aaac1 100644 --- a/src/docs/design/admin-mcp.md +++ b/src/docs/design/admin-mcp.md @@ -277,9 +277,11 @@ Three of task-mcp's disciplines apply unchanged, and for the same reasons: - **Hard caps.** Item counts and text sizes are bounded and truncation is disclosed, in the spirit of `MaxPageSize = 20` and `MaxTextBytes = 16 KiB`. The admin surface caps each result at `MaxTextBytes = 256 KiB` on both transports. An - oversized result is truncated, never turned into an error: the longest top-level lists are - shortened first (`_truncated: true`), and a result that still does not fit becomes a - bounded `text_preview`; either way `_admin_mcp.truncated` is `true` with the original size. + oversized result is truncated, never turned into an error: the top-level list with the most + encoded bytes is halved first, then the next largest, until the result fits + (`_truncated: true`; a long list of small entries is left whole when cutting it would + not help), and a result that still does not fit becomes a bounded `text_preview`; either way + `_admin_mcp.truncated` is `true` with the original size. To them the admin surface adds one the read-only sibling never needed: **no write happens on a single call.** Each write is previewed — reporting exactly what would change, on which diff --git a/src/pkg/adminmcp/polish_test.go b/src/pkg/adminmcp/polish_test.go index 278a06f22f..1c3682b37a 100644 --- a/src/pkg/adminmcp/polish_test.go +++ b/src/pkg/adminmcp/polish_test.go @@ -3,6 +3,7 @@ package adminmcp import ( "context" "encoding/json" + "fmt" "net/http" "net/http/httptest" "strings" @@ -138,3 +139,87 @@ func TestWritesUnavailableReasonFailsFastBeforePreview(t *testing.T) { t.Fatalf("catalogue = %.400s", text) } } + +// The text cap cut the longest list first, by entry count. On a real +// fleet_status (15 agents, 12 repos, 350 KB) that halved three small 15-entry +// lists that freed a few KB, as well as the two lists that were over the cap. +func TestTextCapCutsTheLargestListNotTheLongest(t *testing.T) { + small := func(n int) []any { + out := make([]any, n) + for i := range out { + out[i] = map[string]any{"name": fmt.Sprintf("agent-%02d", i), "cadence": "15m"} + } + return out + } + big := func(n, bytes int) []any { + out := make([]any, n) + for i := range out { + out[i] = map[string]any{"name": fmt.Sprintf("row-%02d", i), "detail": strings.Repeat("x", bytes)} + } + return out + } + // repos alone is over the cap; every other list is longer but tiny. + h := NewHandler(bigProvider{data: map[string]any{ + "status": "ok", + "repos": big(12, 30*1024), + "cadenceMatrix": small(15), + "configuredAgents": small(15), + "acmmPackAgents": small(15), + }}) + data := truncationMeta(t, callToolText(t, h, ToolFleetStatus)) + for _, key := range []string{"cadenceMatrix", "configuredAgents", "acmmPackAgents"} { + if kept, _ := data[key].([]any); len(kept) != 15 { + t.Errorf("%s kept %d of 15 entries; a small list was cut though it could not bring the result under the cap", key, len(kept)) + } + if _, cut := data[key+"_truncated"]; cut { + t.Errorf("%s is marked truncated", key) + } + } + if kept, _ := data["repos"].([]any); len(kept) == 0 || len(kept) >= 12 { + t.Fatalf("repos kept %d of 12", len(kept)) + } + meta, _ := data["_admin_mcp"].(map[string]any) + fields, _ := meta["text_cap_truncated_fields"].([]any) + if len(fields) != 1 || fields[0] != "repos" { + t.Fatalf("text_cap_truncated_fields = %v, want [repos]", fields) + } +} + +// Lists of equal size are cut in name order, so one result is not truncated +// differently from call to call. +func TestTextCapCutsEqualListsInAStableOrder(t *testing.T) { + rows := func() []any { + out := make([]any, 8) + for i := range out { + out[i] = map[string]any{"detail": strings.Repeat("y", 14*1024)} + } + return out + } + var first string + for i := 0; i < 20; i++ { + b, err := EncodeResult(map[string]any{"alpha": rows(), "beta": rows(), "gamma": rows()}) + if err != nil { + t.Fatal(err) + } + if first == "" { + first = string(b) + continue + } + if string(b) != first { + t.Fatalf("call %d truncated the same result differently", i) + } + } + var env struct { + Data map[string]any `json:"data"` + } + if err := json.Unmarshal([]byte(first), &env); err != nil { + t.Fatal(err) + } + // Three 112 KB lists: halving alpha and then beta is enough, so gamma + // is whole. + for key, want := range map[string]int{"alpha": 4, "beta": 4, "gamma": 8} { + if kept, _ := env.Data[key].([]any); len(kept) != want { + t.Errorf("%s kept %d entries, want %d", key, len(kept), want) + } + } +} diff --git a/src/pkg/adminmcp/result_cap.go b/src/pkg/adminmcp/result_cap.go index d043d6d4e5..0aaa5928bc 100644 --- a/src/pkg/adminmcp/result_cap.go +++ b/src/pkg/adminmcp/result_cap.go @@ -37,7 +37,11 @@ func textCapMeta(originalBytes int) map[string]any { } } -// shrinkLists halves the longest top-level list until the envelope fits. +// shrinkLists halves the largest top-level list until the envelope fits. Lists +// are ranked by their encoded size, not their length: halving a long list of +// small entries frees almost nothing, so ranking by length cut such lists +// (and the answers in them) for no gain before it reached the list that was +// actually over the cap. func shrinkLists(data any, originalBytes int) ([]byte, bool) { var out map[string]any switch x := data.(type) { @@ -53,8 +57,9 @@ func shrinkLists(data any, originalBytes int) ([]byte, bool) { } prior, _ := out["_admin_mcp"].(map[string]any) totals := map[string]int{} + sizes := listSizes(out) for round := 0; round < maxShrinkRounds; round++ { - key := longestList(out) + key := largestList(sizes) if key == "" { return nil, false } @@ -62,7 +67,13 @@ func shrinkLists(data any, originalBytes int) ([]byte, bool) { if _, seen := totals[key]; !seen { totals[key] = len(items) } - out[key] = items[:len(items)/2] + kept := items[:len(items)/2] + out[key] = kept + if len(kept) == 0 { + delete(sizes, key) + } else { + sizes[key] = encodedSize(kept) + } out[key+"_truncated"] = true meta := textCapMeta(originalBytes) for k, v := range prior { @@ -81,11 +92,33 @@ func shrinkLists(data any, originalBytes int) ([]byte, bool) { return nil, false } -func longestList(m map[string]any) string { - best, bestLen := "", 0 +// listSizes returns the encoded size of every non-empty top-level list. +func listSizes(m map[string]any) map[string]int { + sizes := map[string]int{} for k, v := range m { - if items, ok := v.([]any); ok && len(items) > bestLen { - best, bestLen = k, len(items) + if items, ok := v.([]any); ok && len(items) > 0 { + sizes[k] = encodedSize(items) + } + } + return sizes +} + +func encodedSize(v any) int { + b, err := json.Marshal(v) + if err != nil { + return 0 + } + return len(b) +} + +// largestList names the list with the most encoded bytes. Equal sizes go to +// the first name in sorted order, so the same result is cut the same way on +// every call. +func largestList(sizes map[string]int) string { + best, bestSize := "", 0 + for k, size := range sizes { + if size > bestSize || (size == bestSize && best != "" && k < best) { + best, bestSize = k, size } } return best