Optimize context token usage with automatic TOON selection

[shaihi]

Summary

• add opt-in format: "auto" for context bundle rendering
• select TOON for shallow, mostly uniform context rows where TOON is likely token-efficient
• fall back to compact JSON for tiny, mixed-shape, or nested-object-heavy bundles
• expose auto through API, MCP, client, tools, and OpenAPI schema
• add local and public-source token-efficiency benchmark checks

Why

TOON can reduce prompt tokens for repeated row-like memory context, but it can be worse than compact JSON for nested or semi-uniform payloads. The auto mode gives users a low-effort way to reduce context token usage without manually inspecting each bundle or accepting TOON regressions.

Existing defaults are unchanged: markdown remains the default, JSON remains the transport/storage format, and this only affects the prompt-ready rendered string when explicitly requested.

Public benchmark check

Run:
bun run benchmark:toon-public --sample-out=docs/benchmarks/toon-public-token-benchmark.sample.json

Source:

• toon-format/toon
• commit a19a1179193451fad40f11ef88de5f363ea3684a
• dataset set: TOKEN_EFFICIENCY_DATASETS

Result vs compact JSON:

• compact JSON: 303,280 tokens
• raw TOON: 295,730 tokens, 2.5% savings
• auto: 266,394 tokens, 12.2% savings
• raw TOON saved on 3/6 public datasets and lost on 3/6
• auto saved on 3/6 and lost on 0/6

Validation

• bun run benchmark:toon-public --public-repo=/tmp/toon-benchmark-inspect --sample-out=docs/benchmarks/toon-public-token-benchmark.sample.json
• bun run benchmark:toon --sample-out=docs/benchmarks/toon-token-benchmark.sample.json
• bun run check-types
• focused Vitest suite for formatter/API/MCP/client behavior
• bun run test
• Biome checks on touched benchmark/docs files