Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Preserve useful diagnostics in bounded tool previews

Rach Pradhan20652a1f7587
diff --git a/docs/adr/0186-tool-previews-use-original-source-ranges.md b/docs/adr/0186-tool-previews-use-original-source-ranges.md
new file mode 100644
index 00000000..4372bb20
--- /dev/null
+++ b/docs/adr/0186-tool-previews-use-original-source-ranges.md
@@ -0,0 +1,32 @@
+# 0186. Tool previews use original source ranges
+
+Status: accepted 2026-09-23
+
+## Context
+
+Oversized tool results retain a head-and-tail preview and a saved full result.
+A rendered preview includes an omission marker, so its length is not an offset
+into the original result. Using that length to select additional diagnostic
+lines can omit useful evidence or repeat a line already visible in the tail.
+Collecting all diagnostic lines before checking their combined size can also
+let one oversized line suppress later useful lines.
+
+## Decision
+
+Carry the original omitted range with the preview. Select whole diagnostic
+lines intersecting that range; exclude lines whose contents are already fully
+visible in the head or tail. Include a boundary-crossing line in full when it
+fits, preserving its meaning and UTF-8 text. A plain-prefix fallback supplies
+its own original range.
+
+Select diagnostic lines within the remaining byte and line budgets before
+allocating their rendered body. Skip a line that does not fit and continue to
+later lines. Report the number of selected lines, without truncating individual
+lines to force them into the preview.
+
+## Consequences
+
+This preserves the full-result handle, output limits, and tool status under
+[ADR 0012](0012-overflow-handles-named-limits-extra-roots.md). A preview remains
+partial, and the saved result remains available for paging. Tests cover omitted
+and already-visible diagnostics, boundary crossings, oversized lines, and UTF-8.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 04f06766..15a4372b 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -211,6 +211,7 @@ record only when you need the evidence or the edge cases.
| [0183](0183-request-policy-owns-ambiguous-retries.md) | Ambiguous HTTP/2 failures return to the request retry policy so attempts and unknown usage remain observable. |
| [0184](0184-directory-scan-budgets-count-examined-entries.md) | Directory scan limits count examined entries before filtering; truncated listings and suggestions remain explicitly partial. |
| [0185](0185-input-semantics-belong-to-the-task-contract.md) | Empty-input, whitespace, and record-framing semantics come from the task contract, not global work instructions. |
+| [0186](0186-tool-previews-use-original-source-ranges.md) | Tool previews select whole diagnostic lines from original omitted ranges within byte and line budgets. |
## When to write one
diff --git a/evals/harness_behavior.jsonl b/evals/harness_behavior.jsonl
index 0d8c396d..83d6dec6 100644
--- a/evals/harness_behavior.jsonl
+++ b/evals/harness_behavior.jsonl
@@ -135,3 +135,5 @@
{"id": "gateway-failure-usage-unknown", "why": "A typed gateway failure with no usage must preserve the provider diagnostic and label totals as incomplete instead of implying a free zero-token call.", "args": ["-p", "summarize the fixture"], "prompt": "summarize the fixture", "script": [{"text": "partial", "stream_error": {"type": "gateway_error", "code": "request_failed", "message": "fixture request failed"}}], "expected_exit": 1, "assert": [{"stderr_contains": "gateway_error request_failed"}, {"stderr_contains": "known subtotal: 0 api call(s)"}, {"stderr_contains": "1 failed request attempt(s) without usage (tokens and cost unknown)"}]}
{"id": "gateway-retry-usage-remains-incomplete", "why": "A recovered retry retains known successful usage while the failed attempt remains explicitly unknown.", "prompt": "summarize the fixture", "script": [{"text": "partial", "stream_error": {"type": "api_error", "message": "Internal error during token parsing"}}, {"text": "recovered fixture"}], "assert": [{"event": {"type": "turn", "usage_complete": false, "unreported_failed_attempts": 1, "api_calls": 1}}, {"final_text_contains": "recovered fixture"}]}
{"id":"atomic-edit-batch-rejects-later-span","why":"A later ambiguous edit span must reject the entire batch without leaving earlier spans on disk; a corrected dependent batch then commits once and verifies.","args":["--old"],"env":{"GRAFF_NO_CODEDB_GUARD":"1"},"workspace_seed":{"f.txt":"alpha beta\nreturn v\nreturn v\n"},"prompt":"Apply the three edits to f.txt, check that a rejected batch left the file unchanged, then correct the ambiguous span and verify the final contents.","script":[{"tool":"edit_file","arguments":{"path":"f.txt","edits":[{"old_string":"alpha","new_string":"ALPHA"},{"old_string":"beta","new_string":"BETA"},{"old_string":"return v","new_string":"return value"}]}},{"tool":"bash","arguments":{"command":"python3 -c \"from pathlib import Path; assert Path('f.txt').read_text() == 'alpha beta\\nreturn v\\nreturn v\\n'; print('UNCHANGED_AFTER_REJECTION')\""}},{"tool":"edit_file","arguments":{"path":"f.txt","edits":[{"old_string":"alpha","new_string":"ALPHA"},{"old_string":"beta","new_string":"BETA"},{"old_string":"return v\nreturn v","new_string":"return value\nreturn value"}]}},{"tool":"bash","arguments":{"command":"python3 -c \"from pathlib import Path; assert Path('f.txt').read_text() == 'ALPHA BETA\\nreturn value\\nreturn value\\n'; print('CORRECTED_BATCH_VERIFIED')\""}},{"text":"The corrected batch passed both file checks."}],"assert":[{"event":{"type":"tool_call_finished","name":"edit_file","is_error":true}},{"event":{"type":"tool_call_finished","name":"edit_file","is_error":false}},{"events_at_most":{"match":{"type":"tool_call_finished","name":"edit_file","is_error":true},"count":1}},{"request_contains":{"index":1,"text":"edit span 3/3 failed"}},{"request_contains":{"index":1,"text":"no batch changes written"}},{"event":{"type":"tool_result","name":"bash","text":"UNCHANGED_AFTER_REJECTION\n"}},{"event":{"type":"tool_result","name":"bash","text":"CORRECTED_BATCH_VERIFIED\n"}},{"file_equals":{"path":"f.txt","content":"ALPHA BETA\nreturn value\nreturn value\n"}},{"final_text_contains":"The corrected batch passed both file checks."}]}
+{"id":"large-log-preview-early-omitted-error","why":"A spilled tool result must surface useful omitted error lines in its first model request without an extra pager call.","args":["--old"],"env":{"GRAFF_NO_CODEDB_GUARD":"1"},"prompt":"Run the diagnostic report and summarize its errors.","script":[{"tool":"shell","arguments":{"command":"python3 -c '[print('\"'\"'ok %04d '\"'\"'%i+'\"'\"'x'\"'\"'*32) for i in range(24)]; print('\"'\"'ERROR '\"'\"'+ '\"'\"'EARLY_'\"'\"'+'\"'\"'GAP_VISIBLE'\"'\"'); [print('\"'\"'ok %04d '\"'\"'%i+'\"'\"'x'\"'\"'*32) for i in range(24,625)]'"}},{"text":"Report reviewed."}],"assert":[{"request_count":2},{"request_contains":{"index":1,"text":"ERROR EARLY_GAP_VISIBLE"}},{"request_contains":{"index":1,"text":"tool result handle"}},{"final_text_contains":"Report reviewed."}]}
+{"id":"large-log-preview-short-error-after-long-line","why":"A spilled tool result must surface useful omitted error lines in its first model request without an extra pager call.","args":["--old"],"env":{"GRAFF_NO_CODEDB_GUARD":"1"},"prompt":"Run the diagnostic report and summarize its errors.","script":[{"tool":"shell","arguments":{"command":"python3 -c '[print('\"'\"'ok %04d '\"'\"'%i+'\"'\"'x'\"'\"'*32) for i in range(100)]; print('\"'\"'ERROR '\"'\"'+ '\"'\"'z'\"'\"'*2500); print('\"'\"'ERROR '\"'\"'+ '\"'\"'SHORT_'\"'\"'+'\"'\"'DETAIL_VISIBLE'\"'\"'); [print('\"'\"'ok %04d '\"'\"'%i+'\"'\"'x'\"'\"'*32) for i in range(100,700)]'"}},{"text":"Report reviewed."}],"assert":[{"request_count":2},{"request_contains":{"index":1,"text":"ERROR SHORT_DETAIL_VISIBLE"}},{"request_contains":{"index":1,"text":"tool result handle"}},{"final_text_contains":"Report reviewed."}]}
diff --git a/src/handle_preview.zig b/src/handle_preview.zig
index 2dcfeb23..9f9b7a1f 100644
--- a/src/handle_preview.zig
+++ b/src/handle_preview.zig
@@ -1,6 +1,6 @@
//! Notable-line excerpt for a #440 handle preview.
//!
-//! The first payload a spill returns is the HEAD of the result. A needle in
+//! The first payload a spill returns includes the head and tail. A needle in
//! the middle (a single FAILED line in a 168 KiB log) is invisible there, so
//! the model pays a follow-up page. This file pulls a bounded set of
//! error-shaped lines into that first payload so the common "what broke?"
@@ -50,32 +50,38 @@ fn lineIsNotable(line: []const u8) bool {
/// Lines after `skip_before` that look like failures, capped. Empty when
/// nothing qualifies or `budget` cannot hold the header plus one line.
pub fn notableExcerpt(arena: Allocator, text: []const u8, skip_before: usize, budget: usize) ![]const u8 {
- if (budget < 40 or skip_before >= text.len) return "";
- var lines: std.ArrayList([]const u8) = .empty;
- var i = skip_before;
- if (i > 0 and text[i - 1] != '\n') {
- if (std.mem.indexOfScalar(u8, text[i..], '\n')) |n| i += n + 1 else return "";
- }
- while (i < text.len and lines.items.len < max_notable_lines) {
+ return notableRange(arena, text, skip_before, text.len, budget);
+}
+
+/// Only select lines intersecting the omitted source range. A partially
+/// visible boundary line may be repeated in full so its evidence is not lost.
+pub fn notableRange(arena: Allocator, text: []const u8, from: usize, until: usize, budget: usize) ![]const u8 {
+ const end = @min(until, text.len);
+ if (budget < 40 or from >= end) return "";
+ var lines: [max_notable_lines][]const u8 = undefined;
+ var count: usize = 0;
+ const header_reserve = "[notable lines, 8 matches]\n".len;
+ var remaining = budget - header_reserve;
+ var i = lineBounds(text, from).lo;
+ while (i < end and count < max_notable_lines) {
const nl = std.mem.indexOfScalar(u8, text[i..], '\n');
- const end = if (nl) |n| i + n else text.len;
- const line = text[i..end];
- if (lineIsNotable(line)) try lines.append(arena, line);
+ const line_end = if (nl) |n| i + n else text.len;
+ const line = text[i..line_end];
+ if (line_end > from and line.len < remaining and lineIsNotable(line)) {
+ lines[count] = line;
+ count += 1;
+ remaining -= line.len + 1;
+ }
i = if (nl) |n| i + n + 1 else text.len;
}
- if (lines.items.len == 0) return "";
-
+ if (count == 0) return "";
var body: std.Io.Writer.Allocating = .init(arena);
- try body.writer.print("[notable lines, {d} match", .{lines.items.len});
- if (lines.items.len != 1) try body.writer.writeByte('e');
- try body.writer.writeAll("]\n");
- for (lines.items) |line| {
+ try body.writer.print("[notable lines, {d} {s}]\n", .{ count, if (count == 1) "match" else "matches" });
+ for (lines[0..count]) |line| {
try body.writer.writeAll(line);
try body.writer.writeByte('\n');
}
- const out = body.writer.buffered();
- if (out.len > budget) return "";
- return out;
+ return body.writer.buffered();
}
test "lineBounds includes the whole line, not an 80-byte pad" {
@@ -138,12 +144,27 @@ fn takeLines(text: []const u8, from_start: bool, max_lines: usize, max_bytes: us
/// First/last excerpt for a spilled result. Empty when `budget` cannot hold
/// a useful head. The full bytes stay on the handle.
+pub const Preview = struct {
+ text: []const u8,
+ omitted_start: usize,
+ omitted_end: usize,
+};
+
+pub fn prefixPreview(text: []const u8, budget: usize) Preview {
+ const prefix = utilUtf8Prefix(text, budget);
+ return .{ .text = prefix, .omitted_start = prefix.len, .omitted_end = text.len };
+}
+
pub fn compactPreview(arena: Allocator, text: []const u8, budget: usize) ![]const u8 {
- if (budget < 80) return utilUtf8Prefix(text, budget);
+ return (try compactPreviewRanges(arena, text, budget)).text;
+}
+
+pub fn compactPreviewRanges(arena: Allocator, text: []const u8, budget: usize) !Preview {
+ if (budget < 80) return prefixPreview(text, budget);
const head = takeLines(text, true, head_lines, @min(head_bytes, budget / 2));
const tail = takeLines(text, false, tail_lines, @min(tail_bytes, budget / 4));
if (tail.len == 0 or std.mem.endsWith(u8, head, tail) or head.len + tail.len >= text.len)
- return arena.dupe(u8, utilUtf8Prefix(text, budget));
+ return prefixPreview(text, budget);
const gap = "[... {d} bytes omitted; page with read_tool_result(handle, offset, limit) or query ...]\n";
const omitted = text.len - head.len - tail.len;
var aw: std.Io.Writer.Allocating = .init(arena);
@@ -152,8 +173,8 @@ pub fn compactPreview(arena: Allocator, text: []const u8, budget: usize) ![]cons
try aw.writer.print(gap, .{omitted});
try aw.writer.writeAll(tail);
const out = aw.writer.buffered();
- if (out.len > budget) return arena.dupe(u8, utilUtf8Prefix(text, budget));
- return out;
+ if (out.len > budget) return prefixPreview(text, budget);
+ return .{ .text = out, .omitted_start = head.len, .omitted_end = text.len - tail.len };
}
fn utilUtf8Prefix(text: []const u8, n: usize) []const u8 {
diff --git a/src/main.zig b/src/main.zig
index 77367b25..414652b9 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -564,7 +564,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("prompt_astra.zig"), @import("prompt_guidance.zig") }; // per-model guidance (Astra, GPT-5.6)
_ = .{ @import("agent_empty_completion.zig"), @import("agent_model_loop.zig"), @import("publication_policy_tests.zig"), @import("jobs_completion_tests.zig") };
_ = .{ @import("provider_routing_tests.zig"), @import("history_wire.zig"), @import("readline_paste_number_tests.zig"), @import("test_hooks.zig"), @import("peer_wake_loop.zig") };
- _ = @import("list_dir_nearmiss.zig");
+ _ = .{ @import("list_dir_nearmiss.zig"), @import("tool_preview_tests.zig") };
_ = @import("repo_map.zig");
_ = @import("agent_overflow_tests.zig"); // #414: and, through it, agent_overflow.zig's table tests
_ = @import("agent_gateway_retry.zig"); // #1019: flake vs overflow classification must stay reachable
diff --git a/src/tool_handle.zig b/src/tool_handle.zig
index a70a33a1..486ae053 100644
--- a/src/tool_handle.zig
+++ b/src/tool_handle.zig
@@ -143,8 +143,9 @@ pub fn forResult(gpa: Allocator, arena: Allocator, target: Target, text: []const
const preview_cap = @min(room, @as(usize, 4096));
const excerpt_budget = @min(handle_preview.max_notable_bytes, preview_cap / 4);
const head_budget = if (preview_cap > excerpt_budget) preview_cap - excerpt_budget else preview_cap;
- const head = handle_preview.compactPreview(arena, text, head_budget) catch util.utf8Prefix(text, head_budget);
- const excerpt = handle_preview.notableExcerpt(arena, text, head.len, excerpt_budget) catch "";
+ const preview = handle_preview.compactPreviewRanges(arena, text, head_budget) catch handle_preview.prefixPreview(text, head_budget);
+ const head = preview.text;
+ const excerpt = handle_preview.notableRange(arena, text, preview.omitted_start, preview.omitted_end, excerpt_budget) catch "";
if (excerpt.len == 0) return .{
.text = try std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ head, marker }),
.path = path,
diff --git a/src/tool_preview_tests.zig b/src/tool_preview_tests.zig
new file mode 100644
index 00000000..d9f1f2df
--- /dev/null
+++ b/src/tool_preview_tests.zig
@@ -0,0 +1,87 @@
+//! Source-range and bounded-evidence regressions for spilled tool results.
+const std = @import("std");
+const handle = @import("tool_handle.zig");
+const preview = @import("handle_preview.zig");
+
+fn fixture(a: std.mem.Allocator, early: bool, tail: bool) ![]const u8 {
+ var out: std.Io.Writer.Allocating = .init(a);
+ for (0..3000) |i| {
+ if (early and i == 25) try out.writer.writeAll("ERROR omitted-first\n") else if (tail and i == 2999) try out.writer.writeAll("ERROR tail-evidence\n") else try out.writer.print("line {d}\n", .{i});
+ }
+ return out.writer.buffered();
+}
+
+fn render(a: std.mem.Allocator, tmp: *std.testing.TmpDir, text: []const u8) ![]const u8 {
+ const got = try handle.forResult(std.testing.allocator, a, .{ .io = std.testing.io, .dir = tmp.dir, .run_id = "test" }, text, 4096);
+ try std.testing.expect(got.path != null);
+ try std.testing.expectEqual(text.len, got.bytes);
+ try std.testing.expect(got.text.len <= 4096);
+ try std.testing.expect(std.unicode.utf8ValidateSlice(got.text));
+ const stored = try tmp.dir.readFileAlloc(std.testing.io, handle.handles_dir ++ "/tr_0.txt", a, .limited(1 << 20));
+ try std.testing.expectEqualStrings(text, stored);
+ return got.text;
+}
+
+test "spill preview retains first omitted error using original source offsets" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ handle.resetForTest();
+ defer handle.resetForTest();
+ const text = try fixture(arena.allocator(), true, false);
+ const got = try render(arena.allocator(), &tmp, text);
+ try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, got, "ERROR omitted-first"));
+}
+
+test "spill preview does not duplicate error lines already in its tail" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ var tmp = std.testing.tmpDir(.{});
+ defer tmp.cleanup();
+ handle.resetForTest();
+ defer handle.resetForTest();
+ const text = try fixture(arena.allocator(), false, true);
+ const got = try render(arena.allocator(), &tmp, text);
+ try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, got, "ERROR tail-evidence"));
+}
+
+test "spill preview skips oversized notable line but retains later whole UTF8 evidence" {
+ var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena.deinit();
+ const a = arena.allocator();
+ const large = try a.alloc(u8, 8192);
+ @memset(large, 'x');
+ const text = try std.fmt.allocPrint(a, "ERROR {s}\nERROR café 原因\nERROR final\n", .{large});
+ var storage: [512]u8 = undefined;
+ var bounded = std.heap.FixedBufferAllocator.init(&storage);
+ const got = try preview.notableExcerpt(bounded.allocator(), text, 0, 128);
+ try std.testing.expect(std.mem.indexOf(u8, got, "ERROR café 原因\n") != null);
+ try std.testing.expect(std.mem.indexOf(u8, got, "ERROR final\n") != null);
+ try std.testing.expect(got.len <= 128);
+ try std.testing.expect(std.unicode.utf8ValidateSlice(got));
+}
+
+test "spill preview whole UTF8 lines survive both omitted boundaries and prefix fallback" {
+ const a = std.testing.allocator;
+ var arena = std.heap.ArenaAllocator.init(a);
+ defer arena.deinit();
+ const text = "visible\nERROR café 原因\nERROR tail crossing\nERROR fully visible tail\n";
+ const from = std.mem.indexOf(u8, text, "é").? + 1;
+ const until = std.mem.indexOf(u8, text, "crossing").? + 2;
+ const got = try preview.notableRange(arena.allocator(), text, from, until, 256);
+ try std.testing.expect(std.mem.indexOf(u8, got, "ERROR café 原因\n") != null);
+ try std.testing.expect(std.mem.indexOf(u8, got, "ERROR tail crossing\n") != null);
+ try std.testing.expect(std.mem.indexOf(u8, got, "fully visible tail") == null);
+ try std.testing.expect(std.unicode.utf8ValidateSlice(got));
+ const fully_shown = "ERROR shown\nERROR omitted\n";
+ const at_newline = try preview.notableRange(arena.allocator(), fully_shown, "ERROR shown".len, fully_shown.len, 256);
+ try std.testing.expect(std.mem.indexOf(u8, at_newline, "ERROR shown") == null);
+ try std.testing.expect(std.mem.indexOf(u8, at_newline, "ERROR omitted") != null);
+ const prefix = preview.prefixPreview(text, from);
+ try std.testing.expectEqual(prefix.text.len, prefix.omitted_start);
+ try std.testing.expectEqual(text.len, prefix.omitted_end);
+ try std.testing.expect(std.unicode.utf8ValidateSlice(prefix.text));
+ const fallback = try preview.notableRange(arena.allocator(), text, prefix.omitted_start, prefix.omitted_end, 256);
+ try std.testing.expect(std.mem.indexOf(u8, fallback, "ERROR café 原因\n") != null);
+}