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/fixed-admin-mcp-text-cap-largest-list.md
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 5 additions & 3 deletions src/docs/design/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 (`<field>_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
(`<field>_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
Expand Down
85 changes: 85 additions & 0 deletions src/pkg/adminmcp/polish_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package adminmcp
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"strings"
Expand Down Expand Up @@ -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)
}
}
}
47 changes: 40 additions & 7 deletions src/pkg/adminmcp/result_cap.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -53,16 +57,23 @@ 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
}
items := out[key].([]any)
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 {
Expand All @@ -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
Expand Down
Loading