feat(k8s): add a limit parameter to k8s_get_resources

[anjosluc]

Closes #82

What this changes

Adds an optional limit parameter to k8s_get_resources that caps how many resources a call returns. limit=0 returns everything.

Before this, the tool had no way to bound its result size. An agent calling it with all_namespaces=true on a large cluster gets every row of every namespace in one tool result, which goes straight into the model's context. In our production estate that is the largest single source of context growth — turns issuing a few cluster-wide calls reached several million input tokens and exhausted the context window, which ends the turn with an error rather than a large-but-usable answer. Prompt guidance reduced how often it happened but could not prevent it, because the tool still permitted the unbounded call.

How it works

Truncation is applied per output format, because slicing lines out of a structured document would return an invalid one:

output	Behaviour
wide, name, custom-columns…, unset	Cut by row, preserving the NAME header
json	Cut at the items array, so the document stays parseable
yaml, jsonpath, go-template	Left untouched — no equally safe cut point

A single object rather than a list (for example -o json with a resource_name) is returned untouched, and unparseable output is passed through rather than guessed at.

A truncated result carries a notice naming the totals:

... truncated: showing 200 of 1834 resources. Narrow with namespace or resource_name, or pass limit=0 for all.

That notice is as important as the cap. A silently shortened listing reads as complete, so the model would draw conclusions from partial data — worse than the original problem.

Decision I would like your input on

The default is a finite cap (200) rather than unlimited, which changes behaviour for existing callers.

I chose a finite default because it is the only version that protects an agent that does not know to pass the parameter, and that is the case causing real failures for us. The truncation notice keeps it honest, and limit=0 restores the old behaviour exactly.

The trade-off is real though, and if you would rather this be strictly opt-in I am happy to flip the default to 0 — it is a one-line change plus a test. Please say which you prefer.

Tests

Added seven cases to TestHandleKubectlGetEnhanced in pkg/k8s/k8s_test.go, covering truncation, a listing under the limit, limit=0, the default limit, JSON items truncation (asserting the result still parses), YAML passthrough, and a single JSON object.

I verified the new tests actually bite by reverting pkg/k8s/k8s.go to main and confirming they fail, then restoring it and confirming they pass.

make test-only   # 0 failures; pkg/k8s coverage 83.4% (was 80.4%)
make lint        # clean

make build passes. I did not run make e2e, which needs a cluster — CI covers it on Kind.

Documentation

The tool's own MCP description documents the new parameter. I did not touch README.md: its Kubernetes section lists tool names only, no parameters, so there was nothing parameter-level to update. Happy to add something if you would like it documented there.