diff --git a/internal/gateway/stream.go b/internal/gateway/stream.go index dfd059164..63c46f35e 100644 --- a/internal/gateway/stream.go +++ b/internal/gateway/stream.go @@ -80,103 +80,145 @@ func toolPreview(name, output string) string { if strings.TrimSpace(content) == "" { return "completed" } - // A tool that reported a real total is the only trustworthy source for - // how much came back; anything we compute is about the sample we can see. - if total, ok := toolReportedTotal(content); ok { - return total - } - if summary, ok := searchResultSummary(content); ok { + // A notice the tool printed is the only trustworthy source for how much + // came back; anything counted here describes the visible sample. + if summary, ok := toolNoticeSummary(content); ok { return summary } + // Only a search gets a counted summary. A compiler or linter diagnostic has + // the same "file.go:42: message" shape as a search hit, so counting every + // tool's output would report a build error as "3 matches" and hide the very + // output the operator asked for. + if isSearchTool(name) { + if summary, ok := searchResultSummary(content); ok { + return summary + } + } preview := firstInformativeLine(content) if preview == "" { return "completed with no printable preview" } - _ = name return preview } -// toolReportedTotal extracts the line total from the truncation notices the -// tool layer prints (internal/tools/builtin: "[truncated: showing 2/194 lines, -// …]"). Those notices are metadata, not content, so they are never rendered as -// a preview line -- quoting one is what produced "[truncated: showing 3/197 -// lines, 412B/24.1KB]" as if it were a search hit. +// searchToolNames are the tools whose output is a set of matches, and so reads +// better counted than sampled. Every other tool is described by its first +// informative line. +var searchToolNames = map[string]bool{ + "grep": true, + "rg": true, + "search": true, + "toolsearch": true, +} + +func isSearchTool(name string) bool { + return searchToolNames[strings.ToLower(strings.TrimSpace(name))] +} + +// toolNoticeSummary renders the "how much came back" summary from the +// truncation notice the tool printed, if any. // -// A notice that shows everything (showing N/N) is not a truncation and gets no -// summary: the content speaks for itself. -func toolReportedTotal(content string) (string, bool) { +// Two notice shapes exist (internal/tools/builtin): shell prints "[truncated: +// showing last N/M lines, …]" and the other tools print "[truncated: showing +// N/M lines, …]". Both are metadata, never content, so both must be recognised +// -- missing the "last" form would quote the raw notice as the preview, which +// is the exact defect this change removes. +// +// The same notice also tells us WHICH END was kept, which changes the summary: +// a head-truncation ("showing 3/197") lost the tail, so "showing 3" describes +// the sample; a tail-truncation ("showing last 66/97") lost the head, so the +// count of what is visible says nothing useful about the whole. +func toolNoticeSummary(content string) (string, bool) { for line := range strings.SplitSeq(content, "\n") { - line = strings.TrimSpace(line) - shown, total, ok := parseTruncationNotice(line) + notice, ok := parseTruncationNotice(strings.TrimSpace(line)) if !ok { continue } - if total <= shown { - continue + if notice.total <= notice.shown { + continue // showing everything is not a truncation } - return fmt.Sprintf("%d lines total; showing %d", total, shown), true + if notice.truncatedHead { + return fmt.Sprintf("%d lines total; showing last %d", notice.total, notice.shown), true + } + return fmt.Sprintf("%d lines total; showing %d", notice.total, notice.shown), true } return "", false } -// parseTruncationNotice reads "showing / lines" out of a -// truncation notice, tolerating the surrounding "[truncated: … ]" wrapper. -func parseTruncationNotice(line string) (shown, total int, ok bool) { +// truncationNotice describes how much a tool reported and which end it kept. +type truncationNotice struct { + shown int + total int + truncatedHead bool // the kept lines are the tail ("showing last N/M") +} + +// parseTruncationNotice reads "/ lines" out of a truncation +// notice, accepting both the plain and the "showing last" form and tolerating +// the surrounding "[truncated: … ]" wrapper. +func parseTruncationNotice(line string) (truncationNotice, bool) { _, rest, found := strings.Cut(line, "showing ") if !found { - return 0, 0, false + return truncationNotice{}, false + } + truncatedHead := false + if after, ok := strings.CutPrefix(rest, "last "); ok { + rest, truncatedHead = after, true } counts, _, found := strings.Cut(rest, " lines") if !found { - return 0, 0, false + return truncationNotice{}, false } left, right, found := strings.Cut(counts, "/") if !found { - return 0, 0, false + return truncationNotice{}, false } shown, errShown := strconv.Atoi(strings.TrimSpace(left)) total, errTotal := strconv.Atoi(strings.TrimSpace(right)) if errShown != nil || errTotal != nil { - return 0, 0, false + return truncationNotice{}, false } - return shown, total, true + return truncationNotice{shown: shown, total: total, truncatedHead: truncatedHead}, true } -// searchResultSummary counts match lines in ripgrep-shaped output ("path-12- -// text", "path:12:text", or a context separator). A search is the one tool -// whose raw output is least useful quoted and most useful counted, so it is -// summarised rather than sampled. +// searchResultSummary counts the match lines in ripgrep-shaped output. Only +// matches are counted: with context requested, ripgrep also emits context lines +// ("path-12-text", hyphen separator) and "--" group separators, and counting +// those would report the match count plus every context line around it. func searchResultSummary(content string) (string, bool) { - matches, _ := countSearchMatches(content) + matches := countSearchMatches(content) if matches == 0 { return "", false } return fmt.Sprintf("%d %s", matches, pluralize(matches, "match", "matches")), true } -// countSearchMatches counts match lines and whether any were truncated. -func countSearchMatches(content string) (matches int, truncated bool) { +// countSearchMatches counts lines using ripgrep's match separator (":"). +func countSearchMatches(content string) int { + matches := 0 for line := range strings.SplitSeq(content, "\n") { - line = strings.TrimSpace(line) - if line == "" || strings.HasPrefix(line, "[") { - continue - } - if searchMatchLine(line) { + if isSearchMatchLine(strings.TrimSpace(line)) { matches++ } } - return matches, false + return matches } -// searchMatchLine reports whether line has ripgrep's "path-N-text" or -// "path:N:text" shape. The path may contain colons, so the separator is found -// by scanning for the last one that is followed by a line number. -func searchMatchLine(line string) bool { - if strings.HasPrefix(line, "--") && strings.Trim(line, "-") == "" { - return true // context separator +// isSearchMatchLine reports whether line has ripgrep's "path:N:text" match +// shape -- a colon separator. The hyphen form ("path-N-text") is a CONTEXT +// line, not a match, and "--" is a group separator between context blocks; +// neither is a match and neither is counted. +// +// The path may itself contain colons, so the separator is located by scanning +// from the end for a colon followed by digits and another colon. +func isSearchMatchLine(line string) bool { + if line == "" || strings.HasPrefix(line, "[") { + return false + } + if strings.Trim(line, "-") == "" { + return false // "--" group separator } for i := len(line) - 1; i > 0; i-- { - if line[i] != ':' && line[i] != '-' { + if line[i] != ':' { continue } digits := line[i+1:] @@ -184,10 +226,9 @@ func searchMatchLine(line string) bool { for end < len(digits) && digits[end] >= '0' && digits[end] <= '9' { end++ } - if end == 0 || end >= len(digits) { - continue - } - if digits[end] == ':' || digits[end] == '-' { + // Require :: -- the trailing colon distinguishes a + // match from a "path:42" reference with nothing after it. + if end > 0 && end < len(digits) && digits[end] == ':' { return true } } @@ -195,7 +236,7 @@ func searchMatchLine(line string) bool { } // firstInformativeLine returns the first line worth showing: not blank, not a -// module-cache path, and not a truncation notice (which is metadata the total +// module-cache path, and not a truncation notice (which is metadata the notice // path already consumed). func firstInformativeLine(content string) string { for line := range strings.SplitSeq(content, "\n") { @@ -206,7 +247,7 @@ func firstInformativeLine(content string) string { if strings.Contains(line, "/pkg/mod/") { continue } - if _, _, ok := parseTruncationNotice(line); ok { + if _, ok := parseTruncationNotice(line); ok { continue } return truncateRunes(line, 120) diff --git a/internal/gateway/tool_render_report_test.go b/internal/gateway/tool_render_report_test.go index 21f2f233f..f5b5d2e4d 100644 --- a/internal/gateway/tool_render_report_test.go +++ b/internal/gateway/tool_render_report_test.go @@ -1,85 +1,136 @@ package gateway import ( - "fmt" "strings" "testing" ) -// Operator report (2026-09-17): tool output in Telegram is unreadable. A -// grep-heavy turn rendered as a wall of blocks like: +// Operator report (2026-09-17): tool output in the Telegram channel was +// unreadable. A grep-heavy turn rendered as a wall of fenced blocks, each +// quoting one arbitrary match line under a heading that said only +// "grep — done": // // 🔧 grep — done -// ```text -// /home/sam/.claude/config.json-322- } +// /path/config.json-322- } // … 194 more lines -// ``` // -// Three faults, all in the render path: +// One call rendered as 86 runes carrying no usable information: a path, a line +// number, and a stray closing brace. The renderer now describes the result +// instead of quoting it, and never states a count it computed itself. // -// 1. the preview is an arbitrary match line -- a path, a line number and a -// stray brace -- with no statement of what matched or how much; -// 2. the "… N more lines" we append disagrees with the count the tool -// already printed, so one result set shows two different numbers; -// 3. a grep result ends with the tool's own truncation notice, which the -// preview renders as if it were a match. - -// TestGrepContextPreviewIsNotAnArbitraryMatchLine: the first line of ripgrep -// context output is a path, a line number and (here) a closing brace. Showing -// it tells the operator nothing about the search. -func TestGrepContextPreviewIsNotAnArbitraryMatchLine(t *testing.T) { - output := strings.Join([]string{ - "/home/sam/.claude/config.json-322- }", - "/home/sam/.claude/config.json-323- }", - "/home/sam/.claude/config.json-324- }", +// Cases are table-driven per the development protocol in AGENTS.md. +func TestToolPreviewDescribesTheResult(t *testing.T) { + // A 197-line grep result whose first visible line is an arbitrary match; + // the tool's own notice is the only trustworthy total. + truncatedGrep := strings.Join([]string{ + "/home/example/.config/app.json-322- }", + "/home/example/.config/app.json-323- }", + "/home/example/.config/app.json-324- }", "", "[truncated: showing 3/197 lines, 412B/24.1KB]", }, "\n") - got := RenderToolCall(ToolCallEvent{Name: "grep", Output: output}) - - if strings.Contains(got, "config.json-322-") { - t.Errorf("preview is an arbitrary match line, not a summary:\n%s", got) + tests := []struct { + name string + tool string + output string + want string + }{ + { + name: "truncated search reports the tool's total, which is a head truncation", + tool: "grep", + output: truncatedGrep, + want: "197 lines total; showing 3", + }, + { + name: "shell truncation notice says 'showing last' and is still metadata, not content", + tool: "shell", + output: strings.Join([]string{ + "[truncated: showing last 66/97 lines, 46.2KB/164.8KB]", + "", + "the last line of the output", + }, "\n"), + want: "97 lines total; showing last 66", + }, + { + name: "an untruncated search is counted, not sampled", + tool: "grep", + output: "/src/a.go:12:func main() {\n/src/b.go:40:\treturn nil\n/src/c.go:99:}", + want: "3 matches", + }, + { + name: "search context lines are not matches", + tool: "grep", + output: strings.Join([]string{ + "/src/a.go:12:func main() {", + "/src/a.go-13-\treturn nil", + "/src/a.go-14-}", + "--", + "/src/b.go:40:\treturn nil", + }, "\n"), + want: "2 matches", + }, + { + name: "a single match is singular", + tool: "grep", + output: "/src/a.go:12:func main() {", + want: "1 match", + }, + { + name: "a colon in the path does not hide the match", + tool: "grep", + output: "/src/weird:dir/a.go:12:func main() {", + want: "1 match", + }, + { + // A compiler diagnostic has the same "file:line:text" shape as a + // search hit. Counting it would report a build error as "N matches" + // and hide the diagnostic the operator actually needs. + name: "a compiler diagnostic is shown, not counted as matches", + tool: "shell", + output: "internal/webui/api_tasks.go:42: undefined: forgeLocator", + want: "internal/webui/api_tasks.go:42: undefined: forgeLocator", + }, + { + name: "a non-search tool keeps its first informative line", + tool: "find", + output: "/home/example/projects/app\n/home/example/projects/app/internal", + want: "/home/example/projects/app", + }, + { + name: "module-cache noise is skipped", + tool: "read", + output: "/home/example/go/pkg/mod/github.com/x/y@v1.0/z.go\npackage y", + want: "package y", + }, + { + name: "empty output is reported as completed without a preview", + tool: "shell", + output: " \n ", + want: "completed", + }, } - if strings.Contains(got, "[truncated:") { - t.Errorf("preview quoted the tool's truncation notice as content:\n%s", got) - } - // A summary is expected: the operator needs to know how much matched. - if !strings.Contains(got, "197") { - t.Errorf("preview does not state the result size; want the tool's own 197 lines:\n%s", got) - } -} -// TestToolPreviewDoesNotStateItsOwnLineCount: the renderer recomputes a line -// count from the previewed text instead of using the total the tool already -// reported, so the operator sees two different numbers for one result set -- -// the tool's "194 more lines" and our "… 3 more lines". Any count we invent -// from a truncated preview is wrong by construction, so the renderer must not -// state one at all. -func TestToolPreviewDoesNotStateItsOwnLineCount(t *testing.T) { - output := strings.Join([]string{ - "/a/b.go-12- return nil", - "/a/c.go-40- return nil", - "", - "[truncated: showing 2/194 lines, 300B/12.0KB]", - }, "\n") - - got := RenderToolCall(ToolCallEvent{Name: "grep", Output: output}) - - if strings.Contains(got, "more lines") { - t.Errorf("renderer invented a line count from a truncated preview; the tool's own count is the only true one:\n%s", got) - } - // The tool's real total should be what survives. - if !strings.Contains(got, "194") { - t.Errorf("render lost the tool's real total (194 lines):\n%s", got) + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + got := RenderToolCall(ToolCallEvent{Name: tc.tool, Output: tc.output}) + if !strings.Contains(got, tc.want) { + t.Errorf("preview missing %q:\n%s", tc.want, got) + } + // The renderer must never state a count it computed from its own + // truncated sample: that produced two different numbers for one + // result set ("194 more lines" beside "… 3 more lines"). + if strings.Contains(got, "more lines") && !strings.Contains(got, "lines total") { + t.Errorf("renderer invented a line count from its own sample:\n%s", got) + } + }) } } // TestToolRenderIsBoundedAndAggregatable: one rendered call must stay small so // a tool-heavy turn cannot crowd the answer out of a single Telegram frame. -// Bounded at 220 runes so 14 calls stay well inside the 3900-rune frame. func TestToolRenderIsBoundedAndAggregatable(t *testing.T) { - output := strings.Repeat("/very/long/path/to/some/file.go-1234- someLineOfSource();\n", 50) + output := strings.Repeat("/very/long/path/to/some/file.go:1234: someLineOfSource();\n", 50) got := RenderToolCall(ToolCallEvent{Name: "grep", Output: output}) if n := len([]rune(got)); n > 220 { t.Errorf("one rendered tool call is %d runes, want <= 220:\n%s", n, got) @@ -89,26 +140,3 @@ func TestToolRenderIsBoundedAndAggregatable(t *testing.T) { t.Errorf("14 rendered calls would consume %d of a 3900-rune frame", n) } } - -// TestToolRenderKeepsShortOutputInformative: bounding must not throw away a -// short result that genuinely fits -- the existing behaviour these tests must -// not regress. -func TestToolRenderKeepsShortOutputInformative(t *testing.T) { - got := RenderToolCall(ToolCallEvent{Name: "shell", Output: "total 8\ndrwxr-xr-x 2 sam sam"}) - if !strings.Contains(got, "total 8") { - t.Errorf("short output lost its content: %q", got) - } -} - -// TestToolRenderCountsMatchesForSearchTools: a search summary should say how -// many matches, which is the one fact that makes it useful. -func TestToolRenderCountsMatchesForSearchTools(t *testing.T) { - var b strings.Builder - for i := range 7 { - fmt.Fprintf(&b, "/src/file%d.go-%d- match\n", i, i*10) - } - got := RenderToolCall(ToolCallEvent{Name: "grep", Output: b.String()}) - if !strings.Contains(got, "7") { - t.Errorf("search preview does not report the match count:\n%s", got) - } -}