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.mdnew file mode 100644index 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.mdindex 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 onediff --git a/evals/harness_behavior.jsonl b/evals/harness_behavior.jsonlindex 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.zigindex 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) ![]constry 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.zigindex 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 reachablediff --git a/src/tool_handle.zig b/src/tool_handle.zigindex 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: []constconst 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.zignew file mode 100644index 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);+}