Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(learn): show both ends of CLI output on a parse failure (#3517)

gglucasscb3ab61d4d57
diff --git a/headroom/learn/analyzer.py b/headroom/learn/analyzer.py
index 978d49f94..1627a19b9 100644
--- a/headroom/learn/analyzer.py
+++ b/headroom/learn/analyzer.py
@@ -602,6 +602,28 @@ def _strip_fenced_json(raw: str) -> dict:
return result
+def _output_snippet(text: str, limit: int = _MAX_SNIPPET_LEN) -> str:
+ """Bounded excerpt of CLI output showing BOTH ends.
+
+ A head-only excerpt cannot diagnose the failure it is attached to. When a
+ model's JSON answer does not parse, the head is valid-looking JSON in every
+ case: what tells a payload truncated mid-value from one with trailing prose
+ after the closing fence is the END of it. Same reasoning as
+ :func:`_failure_detail` tailing stdout -- CLI backends put the interesting
+ part last -- except a parse failure needs the head too, because that is
+ where a wrapper (a fence, a preamble) shows up.
+
+ Returns *text* unchanged when it already fits, so short output -- the common
+ case -- reads exactly as before.
+ """
+ if len(text) <= limit:
+ return text
+ head = limit // 2
+ tail = limit - head
+ omitted = len(text) - limit
+ return f"{text[:head]}\n...[{omitted} chars omitted]...\n{text[-tail:]}"
+
+
def _failure_detail(
stderr: str | None, stdout: str | None, *, result_text: str | None = None
) -> str:
@@ -725,10 +747,10 @@ def _call_cli_llm(
try:
return _strip_fenced_json(result.stdout)
except json.JSONDecodeError as exc:
- stdout_snippet = (result.stdout or "")[:_MAX_SNIPPET_LEN]
+ stdout_snippet = _output_snippet(result.stdout or "")
raise RuntimeError(
f"`{' '.join(cmd)}` returned unparseable output. "
- f"First {_MAX_SNIPPET_LEN} chars:\n{stdout_snippet}"
+ f"Head and tail of the output:\n{stdout_snippet}"
) from exc
@@ -894,19 +916,19 @@ def _call_claude_cli_streaming(
logger.debug("CLI stderr (exit 0): %s", stderr_blob[:_MAX_SNIPPET_LEN])
if final_result is None:
- stdout_snippet = "".join(stdout_lines)[:_MAX_SNIPPET_LEN]
+ stdout_snippet = _output_snippet("".join(stdout_lines))
raise RuntimeError(
f"`{' '.join(cmd)}` did not emit a final `result` event. "
- f"First {_MAX_SNIPPET_LEN} chars of stdout:\n{stdout_snippet}"
+ f"Head and tail of stdout:\n{stdout_snippet}"
)
try:
return _strip_fenced_json(final_result)
except json.JSONDecodeError as exc:
- snippet = final_result[:_MAX_SNIPPET_LEN]
+ snippet = _output_snippet(final_result)
raise RuntimeError(
f"`{' '.join(cmd)}` returned unparseable output. "
- f"First {_MAX_SNIPPET_LEN} chars:\n{snippet}"
+ f"Head and tail of the output:\n{snippet}"
) from exc
diff --git a/tests/test_learn/test_analyzer.py b/tests/test_learn/test_analyzer.py
index 1e54e9e1b..de2f79e88 100644
--- a/tests/test_learn/test_analyzer.py
+++ b/tests/test_learn/test_analyzer.py
@@ -15,6 +15,7 @@ from headroom.learn.analyzer import (
_call_cli_llm,
_call_llm,
_detect_default_model,
+ _output_snippet,
_parse_llm_response,
_resolve_timeout_secs,
_strip_fenced_json,
@@ -971,6 +972,31 @@ class TestCallCliLlm:
with pytest.raises(RuntimeError, match="unparseable output"):
_call_cli_llm("test digest", "claude-cli")
+ def test_claude_cli_unparseable_result_shows_both_ends(self):
+ # A head-only excerpt of a long answer is valid-looking JSON in every
+ # case; the reason it did not parse -- truncated mid-value, or prose
+ # after the closing fence -- is only visible at the end.
+ payload = '```json\n{"context_file_rules": [' + '{"section": "x"}, ' * 400 + "]}\n```"
+ payload += "\n\nLet me know if you want this in another shape!"
+ with patch(
+ "headroom.learn.analyzer.subprocess.Popen",
+ _fake_claude_popen(stdout_lines=[_result_event(payload)]),
+ ):
+ with pytest.raises(RuntimeError) as exc_info:
+ _call_cli_llm("test digest", "claude-cli")
+ message = str(exc_info.value)
+ assert "unparseable output" in message
+ assert "```json" in message, "head is missing"
+ assert "another shape" in message, "tail is missing"
+ assert "chars omitted" in message
+ # Still bounded: the excerpt cannot grow with the payload.
+ assert len(message) < len(payload)
+
+ def test_output_snippet_leaves_short_output_alone(self):
+ assert _output_snippet("short") == "short"
+ edge = "x" * 2000
+ assert _output_snippet(edge) == edge
+
def test_claude_cli_not_installed_raises(self):
popen = MagicMock(side_effect=FileNotFoundError("No such file or directory: 'claude'"))
with patch("headroom.learn.analyzer.subprocess.Popen", popen):