Skip to content

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.md
new file mode 100644
index 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.md
index 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 one
diff --git a/src/mcp_shapes.zig b/src/mcp_shapes.zig
index 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.zig
index 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; with
defer 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.zig
index 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 result
return 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: []c
status.* = 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.zig
index 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);
+}