Skip to content

feat: make CLI and MCP output lean by default - #1597

Open
DeusData wants to merge 26 commits into
mainfrom
feat/lean-output-contract
Open

feat: make CLI and MCP output lean by default#1597
DeusData wants to merge 26 commits into
mainfrom
feat/lean-output-contract

Conversation

@DeusData

Copy link
Copy Markdown
Owner

What does this PR do?

Makes CLI and MCP responses lean by default while preserving the graph answer itself.

  • keeps core graph rows, exact totals, truncation state, and continuation cursors in the default response
  • moves diagnostics, evidence, progress, and other operational detail behind explicit flags/parameters
  • adds semantic-boundary output budgets and lossless, snapshot-bound pagination instead of byte-slicing answers
  • adds response-local directory-prefix dictionaries only when the serialized and token-shape estimates show a material win
  • keeps JSON as an explicit opt-in and adds a quiet CLI mode
  • preserves invalid UTF-8/reversible identities instead of replacing bytes
  • scopes code search to canonical indexed files and keeps scoped file globs portable to BusyBox/Alpine
  • documents the lean/default versus detailed contracts and adds regression/size contracts

Measured output reduction

On the same serialized MCP tools/list fixture:

  • bytes: 23,075 -> 15,071 (-34.7%)
  • cl100k tokens: 5,068 -> 3,478 (-31.4%)
  • o200k tokens: 5,151 -> 3,570 (-30.7%)

For repeated-path result tables, response-local directory compression reduced token-shaped output by 38.3% on Unix paths and 44.5% on Windows paths. Scattered/token-hostile inputs remain uncompressed, so the optimization does not make those responses larger.

Output contract

  • defaults are compact, but not lossy: graph identities/rows, exact counts, safety signals, and continuations remain present
  • max_output_tokens is enforced as a deterministic model-neutral byte ceiling at whole semantic units
  • omissions are explicit and independently pageable
  • cursors are bound to query arguments, result state, and index generation; stale cursors fail closed
  • directory prefixes are response-local, non-recursive, and emitted only above exact savings thresholds

Validation

Final commit:

  • env CBM_NO_CCACHE=1 scripts/test.sh --suites mcp: 253 passed, 2 expected skips, no sanitizer findings

Completed before the final two-file BusyBox portability follow-up:

  • macOS full sanitizer suite: 7,537 passed, 4 expected skips
  • Linux arm64 sanitizer suite: 7,375 passed, 4 expected skips
  • container lint/static-format gate: passed
  • deliberate RED-on-revert checks bound the CLI quiet/runtime, MCP output, search completeness, and watchdog-isolation regressions

The wider final rerun and native Windows completion were stopped to publish the PR; hosted CI is expected to validate the final merge tree. The prior Windows attempt failed in test infrastructure before product tests because a concurrent VM cleanup removed its live temp root; the affected infrastructure files are unchanged by this branch.

Checklist

  • Every commit is signed off
  • Focused tests pass locally on the final commit
  • New behavior is covered by regression and output-size contracts
  • Documentation is updated

Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Signed-off-by: Martin Vogel <martin.vogel.tech@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant