graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
rlm: slim views name their fields, one script fetches and computes, unbound calls print
justrach4b13bc472999
diff --git a/docs/adr/0240-a-slim-view-names-its-fields-and-one-script-fetches-and-computes.md b/docs/adr/0240-a-slim-view-names-its-fields-and-one-script-fetches-and-computes.mdnew file mode 100644index 00000000..0feb77bf--- /dev/null+++ b/docs/adr/0240-a-slim-view-names-its-fields-and-one-script-fetches-and-computes.md@@ -0,0 +1,37 @@+# 0240. A slim view names its fields, one script fetches and computes, and an unbound call prints++Status: accepted 2026-10-03++## Context++ADR 0238 made rlm binds keep the whole MCP result and `print()` show the slim+view. Paired eval runs against a code-mode harness on the same models and+tasks still showed rlm scripts spending calls the task did not need:++- A slim view kept only identity fields and said nothing about the rest, so+ the model printed a sample row, or called `read_tool_result`, just to learn+ which fields existed before it could `project()` one.+- The slim rule said a bind keeps every field, but not where to compute over+ it. Models fetched in one rlm call and computed in a second, paying a whole+ model call to carry a value from one script to the next.+- A bare host call (`read_file("x")`, `each(ids, get_issue)`) with no name to+ bind ran and printed nothing, so the model repeated it with `print()`.++## Decision++- A slim view names the fields of the whole value: the first row's keys+ (or, for an `each()` bind, the first item's first row), capped at 24 names.+ Both the rlm print marker and a direct call's handle marker carry+ `; fields: ...`.+- The slim rule, stated on every MCP load result (ADR 0225), adds: to compute+ over results in the same call, save them and run the computation inside the+ script, with a one-line example (`write_file` then a shell heredoc).+- An rlm statement that calls a host tool, or `each()`, without binding a+ name prints its result (slimmed as `print()` would).++## Consequences++Slim markers are a few dozen bytes longer. A script line that only called a+tool for its side effect now also prints that tool's result. Revisit if traces+show field lists crowding out useful output, or models writing bare calls they+meant as silent side effects.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 98265dc7..4cb3f182 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -265,6 +265,7 @@ record only when you need the evidence or the edge cases.| [0236](0236-rlm-takes-json-literals-and-each-maps-plain-values.md) | `rlm` takes JSON array/object literals as arguments and binds (`name = [...]`, bound names allowed inside); its splitters nest `[]`/`{}`; `each(arr, tool[, field])` passes plain items as is, picks `field` from objects (default: an MCP tool's first parameter) and names the fields it found; an unsupported statement lists the forms that work. || [0237](0237-deepseek-thinks-at-its-low-level-by-default.md) | DeepSeek's default effort (`medium`) sends `reasoning_effort: low` with thinking enabled; `/effort low` still turns thinking off (ADR 0054), and `high` and above are unchanged. || [0238](0238-rlm-binds-keep-the-whole-mcp-result.md) | An MCP call inside an rlm script binds the whole result; `print()` shows the slim view (each item of an `each()` bind cut on its own), `project(x, field)` reads any field (`n`/`latest_author` through a comment list's fold), and `write_file` saves the whole result; inside rlm, `read_tool_result("tr_N")` with no range binds a stored result whole. |+| [0240](0240-a-slim-view-names-its-fields-and-one-script-fetches-and-computes.md) | A slim view names the whole value's fields (`; fields: ...` on rlm print and direct-call handle markers); the slim rule says to compute over results inside the same rlm script; an unbound host call or `each()` in rlm prints its result. |## When to write onediff --git a/src/mcp_shapes.zig b/src/mcp_shapes.zigindex 4376e347..40b48687 100644--- a/src/mcp_shapes.zig+++ b/src/mcp_shapes.zig@@ -358,6 +358,30 @@ pub fn foldField(item: Value, field: []const u8) ?Value {return .{ .string = authorName(items[latestIndex(items)]) orelse "" };}+/// ADR 0240: the field names of a list result's first row (or of an each()+/// bind's first item's first row), comma-separated and capped, so a slim view+/// names what the whole value holds. Null when the payload has no object rows.+pub fn fieldList(alloc: Allocator, payload: []const u8) ?[]u8 {+ const parsed = std.json.parseFromSlice(Value, alloc, std.mem.trim(u8, payload, " \t\r\n"), .{}) catch return null;+ defer parsed.deinit();+ var items = arrayItems(parsed.value) orelse return null;+ if (items.len > 0 and items[0] != .object) items = arrayItems(items[0]) orelse return null;+ if (items.len == 0 or items[0] != .object) return null;+ var aw: Io.Writer.Allocating = .init(alloc);+ defer aw.deinit();+ var it = items[0].object.iterator();+ var n: usize = 0;+ while (it.next()) |e| : (n += 1) {+ if (n == 24 or aw.writer.buffered().len > 280) {+ aw.writer.writeAll(", ...") catch return null;+ break;+ }+ if (n > 0) aw.writer.writeAll(", ") catch return null;+ aw.writer.writeAll(e.key_ptr.*) catch return null;+ }+ return aw.toOwnedSlice() catch null;+}+/// Remember the fat payload, then replace it with the learnt cut when one/// exists. `text` is owned by `gpa`.pub fn takeSlim(gpa: Allocator, text: []u8) []u8 {@@ -377,7 +401,9 @@ pub fn takeSlimKept(gpa: Allocator, keep_in: ?tool_handle.Target, text: []u8) []var arena_state = std.heap.ArenaAllocator.init(gpa);defer arena_state.deinit();const path = tool_handle.keep(arena_state.allocator(), target, text) orelse return cut;- const out = std.fmt.allocPrint(gpa, "{s}\n[slimmed from {d} bytes; the full result is handle {s} (read_tool_result reads any dropped field; in rlm, x = read_tool_result(\"{s}\") binds it whole for project() or write_file())]", .{ cut, text.len, tool_handle.idOf(path), tool_handle.idOf(path) }) catch return cut;+ const fields = fieldList(gpa, text);+ defer if (fields) |f| gpa.free(f);+ const out = std.fmt.allocPrint(gpa, "{s}\n[slimmed from {d} bytes{s}{s}; the full result is handle {s} (read_tool_result reads any dropped field; in rlm, x = read_tool_result(\"{s}\") binds it whole for project() or write_file())]", .{ cut, text.len, if (fields != null) "; fields: " else "", fields orelse "", tool_handle.idOf(path), tool_handle.idOf(path) }) catch return cut;gpa.free(cut);return out;}@@ -520,7 +546,8 @@ pub fn annotate(gpa: Allocator, arena: Allocator, io: Io, cwd: ?[]const u8, text/// where the model first meets the tools. Unsaid, the model wrote code for/// 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.-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.";+/// 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 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 cf5e318f..96acdcac 100644--- a/src/mcp_shapes_tests.zig+++ b/src/mcp_shapes_tests.zig@@ -60,6 +60,7 @@ test "a direct call's slim result names a handle holding the full payload; withdefer gpa.free(kept);try std.testing.expect(std.mem.indexOf(u8, kept, "ISS-1") != null);try std.testing.expect(std.mem.indexOf(u8, kept, "\"state\"") == null); // dropped from the slim view...+ try std.testing.expect(std.mem.indexOf(u8, kept, "; fields: id, title, description, state;") != null); // ...but named (ADR 0240)const at = std.mem.indexOf(u8, kept, "handle tr_") orelse return error.MissingHandle;const id_end = std.mem.indexOfScalarPos(u8, kept, at + 7, ' ') orelse return error.MissingHandle;const rel = try std.fmt.allocPrint(gpa, ".graff/tool-results/{s}.txt", .{kept[at + 7 .. id_end]});@@ -185,3 +186,19 @@ test "the slim rule says an rlm bind keeps every field (ADR 0238)" {try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "binds stay slimmed") == null);try std.testing.expect(std.mem.indexOf(u8, shapes.slim_rule, "write_file") != null);}++test "fieldList names a list result's fields, and an each() bind's inner rows (ADR 0240)" {+ const gpa = std.testing.allocator;+ const rows = shapes.fieldList(gpa, "[{\"id\":\"ISS-1\",\"priority\":2,\"estimate\":3}]") orelse return error.NoFields;+ defer gpa.free(rows);+ try std.testing.expectEqualStrings("id, priority, estimate", rows);+ const nested = shapes.fieldList(gpa, "[[{\"body\":\"b\",\"author\":{\"name\":\"ada\"}}],[]]") orelse return error.NoFields;+ defer gpa.free(nested);+ try std.testing.expectEqualStrings("body, author", nested);+ try std.testing.expect(shapes.fieldList(gpa, "[1,2,3]") == null);+}++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);+}diff --git a/src/rlm.zig b/src/rlm.zigindex 89c9cca2..f721cc56 100644--- a/src/rlm.zig+++ b/src/rlm.zig@@ -296,9 +296,16 @@ fn evalStmt(printed: *std.ArrayList(u8),bind_out: *std.ArrayList(Binding),) !?ToolOutput {- switch (try rlm_mcp.evalEach(ctx, arena, stmt, binds, bind_out, runHost)) {+ // ADR 0240: an each() with no name to bind prints its result.+ const trimmed = std.mem.trim(u8, stmt, " \t");+ const bare_each = std.mem.startsWith(u8, trimmed, "each(");+ const each_stmt = if (bare_each) try std.fmt.allocPrint(arena, "_ = {s}", .{trimmed}) else stmt;+ switch (try rlm_mcp.evalEach(ctx, arena, each_stmt, binds, bind_out, runHost)) {.miss => {},- .ok => return null,+ .ok => {+ if (bare_each) try echoText(ctx, printed, maybeSlim(arena, bind_out.items[bind_out.items.len - 1].text));+ return null;+ },.fail => |e| return e,}switch (try rlm_reduce.evalStmt(arena, ctx.gpa, stmt, binds, bind_out)) {@@ -313,7 +320,9 @@ fn evalStmt(const out = cached orelse runHost(ctx, c);defer if (cached == null) ctx.gpa.free(out.text);if (order.stopped(out)) return try order.copy(ctx.gpa, out);- if (assignName(stmt)) |nm| try bind_out.append(arena, .{ .name = try arena.dupe(u8, nm), .text = try arena.dupe(u8, out.text) });+ if (assignName(stmt)) |nm| {+ try bind_out.append(arena, .{ .name = try arena.dupe(u8, nm), .text = try arena.dupe(u8, out.text) });+ } else try echoText(ctx, printed, maybeSlim(arena, out.text)); // ADR 0240: an unbound call prints its resultreturn null;}if (printArgs(stmt)) |inner| {@@ -332,6 +341,11 @@ fn evalStmt(return .{ .text = try std.fmt.allocPrint(ctx.gpa, "rlm: unsupported statement: {s}\n{s}", .{ stmt, statement_forms }), .is_error = true };}+fn echoText(ctx: ToolCtx, printed: *std.ArrayList(u8), text: []const u8) !void {+ if (printed.items.len > 0) try printed.append(ctx.gpa, '\n');+ try printed.appendSlice(ctx.gpa, text);+}+/// What an unsupported statement could have been (ADR 0236).const statement_forms = "A statement is one of: name = tool(args) · name = each(arr, tool[, field]) · name = len(x) or project(x, field) · name = a literal ([...], {...}, \"text\", 3) or another name · write_file(\"path\", name) · print(name, ...). Nested calls, indexing and operators are not supported: bind each value first.";@@ -381,7 +395,7 @@ fn renderPrintPart(ctx: ToolCtx, arena: Allocator, inner: []const u8, binds: []cstatus.* = try order.copy(ctx.gpa, out);return "";}- if (mcp_shapes.slim(arena, out.text)) |s| return slimNote(arena, s, out.text.len);+ if (mcp_shapes.slim(arena, out.text)) |s| return slimNote(arena, s, out.text);return try arena.dupe(u8, out.text);}// Preserve the historical missing-bind echo, but do not pretend an@@ -398,13 +412,15 @@ fn unsupportedPrint(ctx: ToolCtx, status: *?ToolOutput) ![]const u8 {fn maybeSlim(arena: Allocator, payload: []const u8) []const u8 {const cut = mcp_shapes.slim(arena, payload) orelse return payload;- return slimNote(arena, cut, payload.len);+ return slimNote(arena, cut, payload);}/// ADR 0238: a printed cut says it is one. Unsaid, a model that printed a-/// file it had just saved took the view for the file's contents.-pub fn slimNote(arena: Allocator, cut: []const u8, full: usize) []const u8 {- return std.fmt.allocPrint(arena, "{s}\n[slim view of a {d}-byte value; the value keeps every field: project(x, field) reads one, write_file saves it whole]", .{ cut, full }) catch cut;+/// file it had just saved took the view for the file's contents. ADR 0240:+/// it names the fields the whole value has, so project() needs no probe.+pub fn slimNote(arena: Allocator, cut: []const u8, full: []const u8) []const u8 {+ const fields = mcp_shapes.fieldList(arena, full);+ return std.fmt.allocPrint(arena, "{s}\n[slim view of a {d}-byte value{s}{s}; the value keeps every field: project(x, field) reads one, write_file saves it whole]", .{ cut, full.len, if (fields != null) "; fields: " else "", fields orelse "" }) catch cut;}fn observe(ctx: ToolCtx, call: spec_ptc.Call, out: ToolOutput) !void {diff --git a/src/rlm_tests.zig b/src/rlm_tests.zigindex c6613718..7826cc91 100644--- a/src/rlm_tests.zig+++ b/src/rlm_tests.zig@@ -471,7 +471,44 @@ test "#1016: literal read_file stays native when an MCP short name collides" {test "a printed slim view names itself and the full size (ADR 0238)" {var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);defer arena_state.deinit();- const note = @import("rlm.zig").slimNote(arena_state.allocator(), "[{\"id\":\"ISS-1\"}]", 56005);+ const full: [56005]u8 = @splat('x');+ const note = @import("rlm.zig").slimNote(arena_state.allocator(), "[{\"id\":\"ISS-1\"}]", &full);try std.testing.expect(std.mem.startsWith(u8, note, "[{\"id\":\"ISS-1\"}]\n[slim view of a 56005-byte value"));try std.testing.expect(std.mem.indexOf(u8, note, "write_file") != null);}++test "a printed slim view names the fields the whole value has (ADR 0240)" {+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);+ defer arena_state.deinit();+ const note = @import("rlm.zig").slimNote(arena_state.allocator(), "[{\"id\":\"ISS-1\"}]", "[{\"id\":\"ISS-1\",\"priority\":2,\"estimate\":3}]");+ try std.testing.expect(std.mem.indexOf(u8, note, "-byte value; fields: id, priority, estimate; the value keeps every field") != null);+}++test "an unbound call and a bare each() print their results (ADR 0240)" {+ const gpa = std.testing.allocator;+ const io = std.testing.io;+ var tmp = std.testing.tmpDir(.{});+ defer tmp.cleanup();+ try tmp.dir.writeFile(io, .{ .sub_path = "note.txt", .data = "hello-rlm\n" });+ var path_buf: [std.fs.max_path_bytes]u8 = undefined;+ const n = try tmp.dir.realPath(io, &path_buf);+ var dummy_client: std.http.Client = .{ .allocator = gpa, .io = io };+ defer dummy_client.deinit();+ const saved = rlm.available;+ defer {+ rlm.available = saved;+ rlm.resetLive(gpa, io);+ }+ rlm.available = true;+ var ctx = testCtx(gpa, io, &dummy_client);+ ctx.agent_cwd = path_buf[0..n];+ const bare = try rlm.runScript(ctx, "read_file(\"note.txt\")");+ defer gpa.free(bare.text);+ try std.testing.expect(!bare.is_error);+ try std.testing.expect(std.mem.indexOf(u8, bare.text, "hello-rlm") != null);+ // each() hands a native tool `arg`; sleep_ms takes it (rlm_order_tests does the same).+ const mapped = try rlm.runScript(ctx, "each([1, 2], \"sleep_ms\")");+ defer gpa.free(mapped.text);+ try std.testing.expect(!mapped.is_error);+ try std.testing.expect(std.mem.indexOf(u8, mapped.text, "slept") != null);+}