graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
mcp: a slimmed comment list names its issue (ADR 0257)
justrach636e0ec76e8e
diff --git a/docs/adr/0257-a-slimmed-comment-list-names-its-issue.md b/docs/adr/0257-a-slimmed-comment-list-names-its-issue.mdnew file mode 100644index 00000000..ced9a8ec--- /dev/null+++ b/docs/adr/0257-a-slimmed-comment-list-names-its-issue.md@@ -0,0 +1,31 @@+# 0257. A slimmed comment list names its issue++Status: accepted 2026-10-06++## Context++Large MCP list results are slimmed before the model sees them (ADR 0029,+ADR 0225): a comment list becomes `{"n": count, "latest_author": name}` and+the full result goes to a handle. The fold dropped every field of the rows,+including the issue they belong to.++When a model fetched several issues' comments in one response, each result+came back paired with its call, but nothing in the result itself said which+issue it described. Handles are numbered as results complete, so in a batch+they do not follow the order of the calls. Sub-agents on the eval tasks that+fan out over issues reported the right counts against the wrong issues: the+counts followed the handle numbers, not the calls.++## Decision++When every comment row carries the same parent id (`issueId`, `issue_id`, or+a nested `issue.identifier` / `issue.id`), the fold keeps it first:+`{"issue": "ISS-4", "n": 4, "latest_author": "jay"}`. Rows that disagree, or+any row without the field, fold as before. The load note that states the slim+rule says so.++## Consequences++A result names its own issue, so pairing no longer depends on call order or+handle numbers. The fold grows by one short field when the rows carry it.+Handles stay numbered by completion; nothing should read order into them.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 936c1dbf..cbbbc340 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -282,6 +282,7 @@ record only when you need the evidence or the edge cases.| [0254](0254-imported-conversations-use-the-configured-route.md) | Imported Claude history uses the configured graff provider and credentials; source models are metadata, and foreign tool results remain historical receipts. || [0255](0255-codegraff-claude-uses-native-messages.md) | Claude aliases on codegraff use the native Messages endpoint; `isClaudeApi` is the one predicate for the real Claude wire. || [0256](0256-gemini-takes-fewer-requests-per-task.md) | Gemini models get a working note (chained shell steps, no read-backs, no pasted files, check computed answers) and may batch `attempt_completion` with a final check or write; the completion is recorded only if every batched call succeeded. |+| [0257](0257-a-slimmed-comment-list-names-its-issue.md) | A slimmed MCP comment list keeps the issue id its rows share (`{issue, n, latest_author}`), so parallel results name what they describe. |## When to write onediff --git a/src/mcp_shapes.zig b/src/mcp_shapes.zigindex 40b48687..410329ef 100644--- a/src/mcp_shapes.zig+++ b/src/mcp_shapes.zig@@ -438,36 +438,52 @@ fn latestIndex(items: []const Value) usize {}fn slimComments(alloc: Allocator, items: []const Value) ?[]u8 {- const name = authorName(items[latestIndex(items)]);var aw: Io.Writer.Allocating = .init(alloc);- var s: std.json.Stringify = .{ .writer = &aw.writer };- s.beginObject() catch {- aw.deinit();- return null;- };- s.objectField("n") catch {- aw.deinit();- return null;- };- s.write(items.len) catch {- aw.deinit();- return null;- };- s.objectField("latest_author") catch {- aw.deinit();- return null;- };- s.write(name orelse "") catch {- aw.deinit();- return null;- };- s.endObject() catch {+ writeCommentFold(&aw.writer, items) catch {aw.deinit();return null;};return aw.toOwnedSlice() catch null;}+/// `{issue?, n, latest_author}`. `issue` is the parent every row names: the+/// fold otherwise loses which issue a list belongs to, and a model pairing+/// parallel results by position credited counts to the wrong issue.+fn writeCommentFold(w: *Io.Writer, items: []const Value) !void {+ var s: std.json.Stringify = .{ .writer = w };+ try s.beginObject();+ if (sharedParent(items)) |parent| {+ try s.objectField("issue");+ try s.write(parent);+ }+ try s.objectField("n");+ try s.write(items.len);+ try s.objectField("latest_author");+ try s.write(authorName(items[latestIndex(items)]) orelse "");+ try s.endObject();+}++/// The one parent id every row carries (`issueId`, `issue_id`, or a nested+/// `issue.identifier` / `issue.id`), or null when rows disagree or omit it.+fn sharedParent(items: []const Value) ?[]const u8 {+ for ([_][2][]const u8{ .{ "issueId", "" }, .{ "issue_id", "" }, .{ "issue", "identifier" }, .{ "issue", "id" } }) |path| {+ var shared: ?[]const u8 = null;+ for (items) |item| {+ const v = parentField(item, path[0], path[1]) orelse break;+ if (shared) |prev| if (!std.mem.eql(u8, prev, v)) break;+ shared = v;+ } else if (shared) |v| return v;+ }+ return null;+}++fn parentField(item: Value, key: []const u8, sub: []const u8) ?[]const u8 {+ if (item != .object) return null;+ var v = item.object.get(key) orelse return null;+ if (sub.len > 0) v = if (v == .object) (v.object.get(sub) orelse return null) else return null;+ return if (v == .string) v.string else null;+}+fn authorName(item: Value) ?[]const u8 {if (item != .object) return null;const author = item.object.get("author") orelse return null;@@ -547,7 +563,7 @@ pub fn annotate(gpa: Allocator, arena: Allocator, io: Io, cwd: ?[]const u8, text/// the full rows, failed on the first missing field, and spent calls finding/// the real shape. ADR 0238: rlm binds keep every field; only print() slims./// ADR 0240: computing over the results happens in the same script.-pub const slim_rule = "\nLarge list results from these tools are shown slimmed: rows keep only id/identifier/title/name, and a comment list becomes {\"n\": count, \"latest_author\": name}. A direct call's result names a handle holding the full result. In rlm a bind keeps every field: print() shows the slim view, project(x, field) reads any field, and write_file(\"f.json\", x) saves the whole result for a script. To compute over results in the same call, save them and run the computation inside the script: issues = tool(); write_file(\"issues.json\", issues); r = bash(\"python3 - <<'EOF'\\n...\\nEOF\"); print(r).";+pub const slim_rule = "\nLarge list results from these tools are shown slimmed: rows keep only id/identifier/title/name, and a comment list becomes {\"issue\": its issue when the comments name one, \"n\": count, \"latest_author\": name}. A direct call's result names a handle holding the full result. In rlm a bind keeps every field: print() shows the slim view, project(x, field) reads any field, and write_file(\"f.json\", x) saves the whole result for a script. To compute over results in the same call, save them and run the computation inside the script: issues = tool(); write_file(\"issues.json\", issues); r = bash(\"python3 - <<'EOF'\\n...\\nEOF\"); print(r).";pub fn lookup(io: Io, name: []const u8) ?[]const u8 {store.mu.lockUncancelable(io);diff --git a/src/mcp_shapes_tests.zig b/src/mcp_shapes_tests.zigindex 96acdcac..cb436146 100644--- a/src/mcp_shapes_tests.zig+++ b/src/mcp_shapes_tests.zig@@ -202,3 +202,28 @@ test "the slim rule says to compute inside the same script (ADR 0240)" {try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "run the computation inside the script") != null);try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "write_file(\"issues.json\", issues)") != null);}++test "a comment fold names the issue every row shares, and only then" {+ const gpa = std.testing.allocator;+ const pad: [400]u8 = @splat('x');+ const pad_s: []const u8 = &pad;+ const shared = try std.fmt.allocPrint(gpa, "[{{\"issueId\":\"ISS-4\",\"body\":\"{s}\",\"author\":{{\"name\":\"gus\"}},\"createdAt\":\"2026-08-11\"}},{{\"issueId\":\"ISS-4\",\"body\":\"{s}\",\"author\":{{\"name\":\"jay\"}},\"createdAt\":\"2026-08-12\"}}]", .{ pad_s, pad_s });+ defer gpa.free(shared);+ const folded = shapes.slim(gpa, shared) orelse return error.ExpectedCommentSlim;+ defer gpa.free(folded);+ try std.testing.expectEqualStrings("{\"issue\":\"ISS-4\",\"n\":2,\"latest_author\":\"jay\"}", folded);++ const nested = try std.fmt.allocPrint(gpa, "[{{\"issue\":{{\"id\":\"u1\",\"identifier\":\"ENG-7\"}},\"body\":\"{s}\",\"author\":\"ada\"}},{{\"issue\":{{\"id\":\"u1\",\"identifier\":\"ENG-7\"}},\"body\":\"{s}\",\"author\":\"bev\"}}]", .{ pad_s, pad_s });+ defer gpa.free(nested);+ const nested_fold = shapes.slim(gpa, nested) orelse return error.ExpectedCommentSlim;+ defer gpa.free(nested_fold);+ try std.testing.expect(std.mem.startsWith(u8, nested_fold, "{\"issue\":\"ENG-7\","));++ // Rows that disagree, or a row without the key, name no issue.+ const mixed = try std.fmt.allocPrint(gpa, "[{{\"issueId\":\"ISS-1\",\"body\":\"{s}\",\"author\":\"ada\"}},{{\"issueId\":\"ISS-2\",\"body\":\"{s}\",\"author\":\"bev\"}},{{\"body\":\"{s}\",\"author\":\"cam\"}}]", .{ pad_s, pad_s, pad_s });+ defer gpa.free(mixed);+ const mixed_fold = shapes.slim(gpa, mixed) orelse return error.ExpectedCommentSlim;+ defer gpa.free(mixed_fold);+ try std.testing.expect(std.mem.indexOf(u8, mixed_fold, "issue") == null);+ try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "\"issue\"") != null);+}