graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Zig speculator for programmatic tool calling (sPTC).
//!
//! [spec-ptc](https://github.com/alexzhang13/spec-ptc) overlaps tool work
//! with generation: as a code REPL streams, closed statements whose arguments
//! are literals launch as futures; the real exec claims them. Graff's native
//! loop already fans a finished batch across the pool — this is earlier: the
//! call is visible in partial source before the `rlm` tool argument closes.
//!
//! This module is the language-agnostic half. It does not run tools. A host
//! (rlm.zig) feeds source, launches `Call`s, and claims by canonical key.
const std = @import("std");
const Allocator = std.mem.Allocator;
/// A closed call with literal args, ready to speculate or claim.
pub const Call = struct {
name: []const u8,
/// Canonical JSON object, e.g. `{"path":"a.txt"}`. Arena/gpa-owned.
args_json: []const u8,
pub fn key(self: Call, arena: Allocator) ![]const u8 {
return std.fmt.allocPrint(arena, "{s}\n{s}", .{ self.name, self.args_json });
}
};
/// Incremental source → complete top-level statements (newline-terminated).
pub const Segmenter = struct {
pending: std.ArrayList(u8) = .empty,
pub fn deinit(self: *Segmenter, gpa: Allocator) void {
self.pending.deinit(gpa);
}
/// Append `delta`. Returns newly closed statements (each without the
/// trailing newline). Caller frees the slice; strings alias `pending`
/// until the next feed, so copy what you keep.
pub fn feed(self: *Segmenter, gpa: Allocator, delta: []const u8) ![][]const u8 {
try self.pending.appendSlice(gpa, delta);
return self.takeClosed(gpa);
}
pub fn finish(self: *Segmenter, gpa: Allocator) ![][]const u8 {
if (self.pending.items.len == 0) return &.{};
const tail = std.mem.trim(u8, self.pending.items, " \t\r\n");
if (tail.len == 0) {
self.pending.clearRetainingCapacity();
return &.{};
}
const one = try gpa.alloc([]const u8, 1);
one[0] = try gpa.dupe(u8, tail);
self.pending.clearRetainingCapacity();
return one;
}
fn takeClosed(self: *Segmenter, gpa: Allocator) ![][]const u8 {
var out: std.ArrayList([]const u8) = .empty;
errdefer out.deinit(gpa);
var rest = self.pending.items;
while (std.mem.indexOfScalar(u8, rest, '\n')) |nl| {
const line = std.mem.trim(u8, rest[0..nl], " \t\r");
if (line.len > 0) try out.append(gpa, try gpa.dupe(u8, line));
rest = rest[nl + 1 ..];
}
if (rest.ptr != self.pending.items.ptr) {
const n = rest.len;
std.mem.copyForwards(u8, self.pending.items[0..n], rest);
self.pending.shrinkRetainingCapacity(n);
}
return out.toOwnedSlice(gpa);
}
};
/// Pull a speculatable `name(...)` / `var = name(...)` from one statement.
/// Only literal args (string / int / bool). Returns null for print, comments,
/// or anything that still depends on a runtime value.
/// A value an rlm script bound earlier (rlm_spec.Binding is this type).
pub const Bound = struct { name: []const u8, text: []const u8 };
pub fn extractCall(arena: Allocator, stmt: []const u8) !?Call {
return extractCallBound(arena, stmt, &.{});
}
/// extractCall where a bare name in the arguments passes that bind's text
/// (the latest binding wins). Speculation has no binds, so it never
/// pre-runs a call that needs one.
pub fn extractCallBound(arena: Allocator, stmt: []const u8, binds: []const Bound) !?Call {
const line = stripComment(stmt);
const trimmed = std.mem.trim(u8, line, " \t");
if (trimmed.len == 0) return null;
const call_src = afterOptionalAssign(trimmed) orelse return null;
const open = std.mem.indexOfScalar(u8, call_src, '(') orelse return null;
const name = std.mem.trim(u8, call_src[0..open], " \t");
if (!isCallName(name)) return null;
if (std.mem.eql(u8, name, "print")) return null;
const close = lastParen(call_src) orelse return null;
const inner = call_src[open + 1 .. close];
const args_json = parseArgs(arena, name, inner, binds) catch |err| switch (err) {
error.NeedKeywords => return null,
else => return err,
} orelse return null;
return .{ .name = try arena.dupe(u8, name), .args_json = args_json };
}
pub fn extractCalls(arena: Allocator, statements: []const []const u8) ![]Call {
var out: std.ArrayList(Call) = .empty;
for (statements) |stmt| {
if (try extractCall(arena, stmt)) |c| {
try out.append(arena, c);
continue;
}
// print(read_file("p")) is a print, not an assign — still speculate
// the nested host call so print() can claim the file, not the literal.
if (printInner(stmt)) |inner| {
const parts = try splitTopLevel(arena, inner, ',');
for (parts) |part| {
if (try extractCall(arena, std.mem.trim(u8, part, " \t"))) |c|
try out.append(arena, c);
}
}
}
return out.toOwnedSlice(arena);
}
fn printInner(stmt: []const u8) ?[]const u8 {
const t = std.mem.trim(u8, stmt, " \t");
if (!std.mem.startsWith(u8, t, "print(") or t[t.len - 1] != ')') return null;
return t["print(".len .. t.len - 1];
}
pub fn stripComment(stmt: []const u8) []const u8 {
var i: usize = 0;
var in_str: ?u8 = null;
var esc = false;
while (i < stmt.len) : (i += 1) {
const c = stmt[i];
if (in_str) |q| {
if (esc) {
esc = false;
continue;
}
if (c == '\\') {
esc = true;
continue;
}
if (c == q) in_str = null;
continue;
}
if (c == '"' or c == '\'') {
in_str = c;
continue;
}
if (c == '#') return stmt[0..i];
}
return stmt;
}
fn afterOptionalAssign(stmt: []const u8) ?[]const u8 {
const paren = std.mem.indexOfScalar(u8, stmt, '(') orelse stmt.len;
if (std.mem.indexOfScalar(u8, stmt[0..paren], '=')) |eq| {
// `==` or a comparison is not an assignment we care about.
if (eq + 1 < stmt.len and stmt[eq + 1] == '=') return stmt;
const lhs = std.mem.trim(u8, stmt[0..eq], " \t");
if (!isIdent(lhs)) return null;
return trimStart(stmt[eq + 1 ..], " \t");
}
return stmt;
}
fn isIdent(s: []const u8) bool {
if (s.len == 0) return false;
if (!identStart(s[0])) return false;
for (s[1..]) |c| if (!identCont(c)) return false;
return true;
}
/// `name(...)` or Code Mode `tools.server.tool(...)` / `server.tool(...)`.
/// Not a general dotted expression — two idents, optional `tools.` prefix.
fn isCallName(s: []const u8) bool {
if (isIdent(s)) return true;
var rest = s;
if (std.mem.startsWith(u8, rest, "tools.")) rest = rest["tools.".len..];
const dot = std.mem.indexOfScalar(u8, rest, '.') orelse return false;
if (std.mem.indexOfScalar(u8, rest[dot + 1 ..], '.') != null) return false;
return isIdent(rest[0..dot]) and isIdent(rest[dot + 1 ..]);
}
fn identStart(c: u8) bool {
return (c >= 'A' and c <= 'Z') or (c >= 'a' and c <= 'z') or c == '_';
}
fn identCont(c: u8) bool {
return identStart(c) or (c >= '0' and c <= '9');
}
fn lastParen(s: []const u8) ?usize {
if (s.len == 0 or s[s.len - 1] != ')') return null;
return s.len - 1;
}
const Arg = struct { key: ?[]const u8, value: Value };
const Value = union(enum) {
string: []const u8,
int: i64,
bool: bool,
json: []const u8, // ADR 0236: a JSON array/object literal, canonical text
};
fn parseArgs(arena: Allocator, tool: []const u8, inner: []const u8, binds: []const Bound) !?[]const u8 {
var args: std.ArrayList(Arg) = .empty;
var i: usize = 0;
const src = inner;
skipWs(src, &i);
if (i >= src.len) return try canonicalize(arena, tool, &.{});
while (i < src.len) {
skipWs(src, &i);
if (i >= src.len) break;
var key: ?[]const u8 = null;
const start = i;
if (identStart(src[i])) {
i += 1;
while (i < src.len and identCont(src[i])) i += 1;
const ident = src[start..i];
skipWs(src, &i);
if (i < src.len and src[i] == '=') {
i += 1;
key = ident;
skipWs(src, &i);
} else {
i = start;
}
}
const val = (try parseValue(arena, src, &i, binds)) orelse return null;
try args.append(arena, .{ .key = key, .value = val });
skipWs(src, &i);
if (i >= src.len) break;
if (src[i] != ',') return null;
i += 1;
}
return try canonicalize(arena, tool, args.items);
}
fn parseValue(arena: Allocator, src: []const u8, i: *usize, binds: []const Bound) !?Value {
if (i.* >= src.len) return null;
const c = src[i.*];
if (c == '"' or c == '\'') return .{ .string = (try parseString(arena, src, i)) orelse return null };
if (c == '-' or (c >= '0' and c <= '9')) return parseInt(src, i);
if (takeWord(src, i, "true")) return .{ .bool = true };
if (takeWord(src, i, "false")) return .{ .bool = false };
if (c == '[' or c == '{') {
const literal = @import("rlm_literal.zig");
const end = literal.scan(src, i.*) orelse return null;
const json = literal.render(arena, src[i.*..end], binds) catch return null;
i.* = end;
return .{ .json = json };
}
if (!identStart(c)) return null;
var end = i.* + 1;
while (end < src.len and identCont(src[end])) end += 1;
const name = src[i.*..end];
var n = binds.len;
while (n > 0) {
n -= 1;
if (std.mem.eql(u8, binds[n].name, name)) {
i.* = end;
return .{ .string = binds[n].text };
}
}
return null;
}
fn parseString(arena: Allocator, src: []const u8, i: *usize) !?[]const u8 {
const q = src[i.*];
i.* += 1;
var out: std.ArrayList(u8) = .empty;
var esc = false;
while (i.* < src.len) : (i.* += 1) {
const c = src[i.*];
if (esc) {
try out.append(arena, switch (c) {
'n' => '\n',
't' => '\t',
else => c,
});
esc = false;
continue;
}
if (c == '\\') {
esc = true;
continue;
}
if (c == q) {
i.* += 1;
return @as(?[]const u8, try out.toOwnedSlice(arena));
}
try out.append(arena, c);
}
return null;
}
fn parseInt(src: []const u8, i: *usize) ?Value {
const start = i.*;
if (src[i.*] == '-') i.* += 1;
if (i.* >= src.len or src[i.*] < '0' or src[i.*] > '9') {
i.* = start;
return null;
}
while (i.* < src.len and src[i.*] >= '0' and src[i.*] <= '9') i.* += 1;
const n = std.fmt.parseInt(i64, src[start..i.*], 10) catch return null;
return .{ .int = n };
}
fn takeWord(src: []const u8, i: *usize, word: []const u8) bool {
if (i.* + word.len > src.len) return false;
if (!std.mem.eql(u8, src[i.*..][0..word.len], word)) return false;
const after = i.* + word.len;
if (after < src.len and identCont(src[after])) return false;
i.* = after;
return true;
}
fn trimStart(s: []const u8, cutset: []const u8) []const u8 {
var i: usize = 0;
while (i < s.len and std.mem.indexOfScalar(u8, cutset, s[i]) != null) i += 1;
return s[i..];
}
fn skipWs(src: []const u8, i: *usize) void {
while (i.* < src.len and (src[i.*] == ' ' or src[i.*] == '\t')) i.* += 1;
}
fn canonicalize(arena: Allocator, tool: []const u8, args: []const Arg) ![]const u8 {
var obj: std.json.ObjectMap = .empty;
const field = hostField(tool);
const positional = for (args) |a| {
if (a.key != null) break false;
} else true;
// write_file(path, content) is the one two-argument positional call:
// how a script saves a bound result for the shell to compute over.
if (positional and args.len == 2 and std.mem.eql(u8, tool, "write_file")) {
try putValue(arena, &obj, field, args[0].value);
// The file holds the literal's JSON text.
try putValue(arena, &obj, "content", switch (args[1].value) {
.json => |j| .{ .string = j },
else => |v| v,
});
} else if (args.len == 1 and args[0].key == null) {
// ADR 0236: `tool({"id": "x"})` is `tool(id="x")`, not an object for the first parameter.
const kw: ?std.json.Value = switch (args[0].value) {
.json => |j| try std.json.parseFromSliceLeaky(std.json.Value, arena, j, .{}),
else => null,
};
if (kw != null and kw.? == .object) obj = kw.?.object else try putValue(arena, &obj, field, args[0].value);
} else {
for (args) |a| {
const k = a.key orelse return error.NeedKeywords;
try putValue(arena, &obj, k, a.value);
}
}
var aw: std.Io.Writer.Allocating = .init(arena);
var s: std.json.Stringify = .{ .writer = &aw.writer };
try s.write(std.json.Value{ .object = obj });
return aw.toOwnedSlice();
}
fn hostField(tool: []const u8) []const u8 {
if (std.mem.eql(u8, tool, "read_file")) return "path";
if (std.mem.eql(u8, tool, "edit_file")) return "path";
if (std.mem.eql(u8, tool, "write_file")) return "path";
if (std.mem.eql(u8, tool, "codedb")) return "command";
if (std.mem.eql(u8, tool, "sleep_ms")) return "ms";
if (std.mem.eql(u8, tool, "llm_query")) return "prompt";
if (std.mem.eql(u8, tool, "bash") or std.mem.eql(u8, tool, "shell")) return "command";
if (std.mem.eql(u8, tool, "webfetch")) return "url";
if (std.mem.eql(u8, tool, "subagent")) return "prompt";
if (std.mem.eql(u8, tool, "read_tool_result")) return "handle";
return "arg";
}
/// Split a script on newlines and semicolons that are outside strings and
/// parentheses. Models often emit `a = read_file("x"); b = read_file("y")`
/// on one line; each call must be its own statement or sPTC never launches.
pub fn splitStatements(arena: Allocator, src: []const u8) ![][]const u8 {
var out: std.ArrayList([]const u8) = .empty;
var i: usize = 0;
var start: usize = 0;
var in_str: ?u8 = null;
var esc = false;
var depth: usize = 0;
while (i < src.len) : (i += 1) {
const c = src[i];
if (in_str) |q| {
if (esc) {
esc = false;
continue;
}
if (c == '\\') {
esc = true;
continue;
}
if (c == q) in_str = null;
continue;
}
if (c == '"' or c == '\'') {
in_str = c;
continue;
}
if (c == '(' or c == '[' or c == '{') {
depth += 1;
continue;
}
if ((c == ')' or c == ']' or c == '}') and depth > 0) {
depth -= 1;
continue;
}
if (depth == 0 and (c == ';' or c == '\n')) {
const piece = std.mem.trim(u8, src[start..i], " \t\r");
if (piece.len > 0) try out.append(arena, piece);
start = i + 1;
}
}
const tail = std.mem.trim(u8, src[start..], " \t\r\n");
if (tail.len > 0) try out.append(arena, tail);
return out.toOwnedSlice(arena);
}
/// Comma-split at depth 0 outside strings — `print(a, b)` and keyword lists.
pub fn splitTopLevel(arena: Allocator, src: []const u8, sep: u8) ![][]const u8 {
var out: std.ArrayList([]const u8) = .empty;
var i: usize = 0;
var start: usize = 0;
var in_str: ?u8 = null;
var esc = false;
var depth: usize = 0;
while (i < src.len) : (i += 1) {
const c = src[i];
if (in_str) |q| {
if (esc) {
esc = false;
continue;
}
if (c == '\\') {
esc = true;
continue;
}
if (c == q) in_str = null;
continue;
}
if (c == '"' or c == '\'') {
in_str = c;
continue;
}
if (c == '(' or c == '[' or c == '{') {
depth += 1;
continue;
}
if ((c == ')' or c == ']' or c == '}') and depth > 0) {
depth -= 1;
continue;
}
if (depth == 0 and c == sep) {
const piece = std.mem.trim(u8, src[start..i], " \t");
if (piece.len > 0) try out.append(arena, piece);
start = i + 1;
}
}
const tail = std.mem.trim(u8, src[start..], " \t");
if (tail.len > 0) try out.append(arena, tail);
return out.toOwnedSlice(arena);
}
fn putValue(arena: Allocator, obj: *std.json.ObjectMap, key: []const u8, v: Value) !void {
const jv: std.json.Value = switch (v) {
.string => |s| .{ .string = s },
.int => |n| .{ .integer = n },
.bool => |b| .{ .bool = b },
.json => |j| try std.json.parseFromSliceLeaky(std.json.Value, arena, j, .{}),
};
try obj.put(arena, key, jv);
}
test "Segmenter yields a line only after the newline, then flushes the tail" {
const gpa = std.testing.allocator;
var seg: Segmenter = .{};
defer seg.deinit(gpa);
const none = try seg.feed(gpa, "a = read_file(\"x\")");
defer gpa.free(none);
try std.testing.expectEqual(@as(usize, 0), none.len);
const one = try seg.feed(gpa, "\nb = read_file(\"y\")\n");
defer {
for (one) |s| gpa.free(s);
gpa.free(one);
}
try std.testing.expectEqual(@as(usize, 2), one.len);
try std.testing.expectEqualStrings("a = read_file(\"x\")", one[0]);
try std.testing.expectEqualStrings("b = read_file(\"y\")", one[1]);
}
test "extractCall reads positional and keyword literals; print and names are skipped" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const r = (try extractCall(a, "x = read_file(\"docs/a.txt\")")).?;
try std.testing.expectEqualStrings("read_file", r.name);
try std.testing.expectEqualStrings("{\"path\":\"docs/a.txt\"}", r.args_json);
const k = (try extractCall(a, "codedb(command=\"status\")")).?;
try std.testing.expectEqualStrings("{\"command\":\"status\"}", k.args_json);
const s = (try extractCall(a, "sleep_ms(40)")).?;
try std.testing.expectEqualStrings("{\"ms\":40}", s.args_json);
const q = (try extractCall(a, "n = llm_query(\"summarize this chunk\")")).?;
try std.testing.expectEqualStrings("llm_query", q.name);
try std.testing.expectEqualStrings("{\"prompt\":\"summarize this chunk\"}", q.args_json);
const dotted = (try extractCall(a, "tools.deepwiki.ask_wiki_question(repoName=\"anomalyco/opencode\", question=\"how\")")).?;
try std.testing.expectEqualStrings("tools.deepwiki.ask_wiki_question", dotted.name);
try std.testing.expect(std.mem.indexOf(u8, dotted.args_json, "anomalyco/opencode") != null);
try std.testing.expect(try extractCall(a, "print(x)") == null);
try std.testing.expect(try extractCall(a, "read_file(path)") == null);
try std.testing.expect(try extractCall(a, "# just a comment") == null);
}
test "extractCalls finds independent sleeps in a three-call script" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const src = [_][]const u8{
"a = sleep_ms(40)",
"b = sleep_ms(40)",
"c = sleep_ms(40)",
"print(a)",
};
const calls = try extractCalls(a, &src);
try std.testing.expectEqual(@as(usize, 3), calls.len);
try std.testing.expectEqualStrings("sleep_ms", calls[0].name);
const nested = [_][]const u8{ "print(read_file(\"note.txt\"))", "print(codedb(\"list_dir .\"), bash(\"ls\"))" };
const inside = try extractCalls(a, &nested);
try std.testing.expectEqual(@as(usize, 3), inside.len);
try std.testing.expectEqualStrings("read_file", inside[0].name);
try std.testing.expectEqualStrings("codedb", inside[1].name);
try std.testing.expectEqualStrings("bash", inside[2].name);
}
test "splitStatements breaks semicolon one-liners; strings keep their commas" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const parts = try splitStatements(a, "a = read_file(\"x;y.txt\"); b = bash(\"ls\"); print(a, b)");
try std.testing.expectEqual(@as(usize, 3), parts.len);
try std.testing.expectEqualStrings("a = read_file(\"x;y.txt\")", parts[0]);
try std.testing.expectEqualStrings("b = bash(\"ls\")", parts[1]);
try std.testing.expectEqualStrings("print(a, b)", parts[2]);
const bash = (try extractCall(a, "b = bash(\"ls -la\")")).?;
try std.testing.expectEqualStrings("bash", bash.name);
try std.testing.expectEqualStrings("{\"command\":\"ls -la\"}", bash.args_json);
}
test "extractCall maps subagent(\"task\") onto prompt; two calls stay independent" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const one = (try extractCall(a, "h = subagent(\"review auth\")")).?;
try std.testing.expectEqualStrings("subagent", one.name);
try std.testing.expectEqualStrings("{\"prompt\":\"review auth\"}", one.args_json);
const bg = (try extractCall(a, "subagent(prompt=\"audit tests\", run_in_background=true)")).?;
try std.testing.expectEqualStrings("subagent", bg.name);
try std.testing.expectEqualStrings("{\"prompt\":\"audit tests\",\"run_in_background\":true}", bg.args_json);
const stmts = try splitStatements(a, "a = subagent(\"read a.txt\"); b = subagent(\"read b.txt\")");
const calls = try extractCalls(a, stmts);
try std.testing.expectEqual(@as(usize, 2), calls.len);
try std.testing.expectEqualStrings("{\"prompt\":\"read a.txt\"}", calls[0].args_json);
try std.testing.expectEqualStrings("{\"prompt\":\"read b.txt\"}", calls[1].args_json);
}
test "extractCallBound: a bare bound name passes its text; write_file takes path then content" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const a = arena_state.allocator();
const binds = [_]Bound{ .{ .name = "notes", .text = "old" }, .{ .name = "notes", .text = "a \"quoted\" line" } };
const w = (try extractCallBound(a, "write_file(\"out.json\", notes)", &binds)).?;
try std.testing.expectEqualStrings("write_file", w.name);
const parsed = try std.json.parseFromSliceLeaky(std.json.Value, a, w.args_json, .{});
try std.testing.expectEqualStrings("out.json", parsed.object.get("path").?.string);
try std.testing.expectEqualStrings("a \"quoted\" line", parsed.object.get("content").?.string); // latest bind
const kw = (try extractCallBound(a, "w = write_file(path=\"o.txt\", content=notes)", &binds)).?;
try std.testing.expect(std.mem.indexOf(u8, kw.args_json, "quoted") != null);
// Without binds (speculation) the call is not pre-run; an unknown name is not a call.
try std.testing.expect((try extractCall(a, "write_file(\"out.json\", notes)")) == null);
try std.testing.expect((try extractCallBound(a, "write_file(\"out.json\", missing)", &binds)) == null);
// Other tools keep one positional argument.
try std.testing.expect((try extractCallBound(a, "read_file(\"a\", notes)", &binds)) == null);
// shell is the catalog name for the command tool: its one positional
// argument is `command`, as the tool description tells scripts to use it.
const sh = (try extractCallBound(a, "r = shell(\"python3 x.py\")", &binds)).?;
try std.testing.expectEqualStrings("{\"command\":\"python3 x.py\"}", sh.args_json);
// read_tool_result's one positional argument is its handle (ADR 0238).
try std.testing.expectEqualStrings("{\"handle\":\"tr_0\"}", (try extractCallBound(a, "h = read_tool_result(\"tr_0\")", &binds)).?.args_json);
}