Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
20.5 KB
Raw Blame
//! Default `rlm` tool: one programmatic-tool-calling REPL per call (ADR 0022).
//!
//! On unless `--old` / `--no-rlm` / `GRAFF_OLD=1` / `GRAFF_RLM=0`. `--rlm`
//! and `GRAFF_RLM=1` force it back on. Host functions: `read_file`, `codedb`
//! (real graff tools), `sleep_ms` (overlap proof), `llm_query` (RLM tools-off
//! sub-LM), `print` (answer), plus loaded MCP names (ADR 0029). Leading safe
//! literal reads overlap while streaming; subsequent calls execute lexically.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;

const spec_ptc = @import("spec_ptc.zig");
const tools = @import("tools.zig");
const ToolCtx = tools.ToolCtx;
const ToolOutput = tools.ToolOutput;
const no_local_tools = @import("no_local_tools.zig");
const exec_mod = @import("exec.zig");
const rlm_query = @import("rlm_query.zig");
const rlm_spec = @import("rlm_spec.zig");
const rlm_mcp = @import("rlm_mcp.zig");
const rlm_reduce = @import("rlm_reduce.zig");
const mcp_shapes = @import("mcp_shapes.zig");
const read_miss = @import("read_miss.zig");

pub const tool_name = "rlm";
pub const tool_desc = "Tools as a call-only script, not Python: name = tool(args), args being literals or bound names (a bound name passes its text); no expressions, indexing or comprehensions. To compute over a result, write_file(\"r.json\", name), then shell. Leading read_file/codedb/sleep_ms/llm_query calls overlap; others run in order, stopping on error/cancel/pending. Binds persist. subagent(\"task\") is sidecar-only (critical-path steps stay local). Loaded MCP names are host functions after load_tool_schemas; each(arr, tool, field?) maps a JSON array; len(x)/project(x, field) slim it. print() is the answer.";
/// --lean catalog desc: same contract, no REPL essay. maybeAppend is after
/// compactLeanSpecs, so this is the one-shot wire text.
pub const lean_tool_desc = "Batch independent read_file/codedb here. print(read_file(\"p\")) returns the file — do not catalog-read it again. Then edit_file/write_file/shell as catalog tools. Leading reads overlap; other calls run in order, stopping on error/cancel/pending. Binds persist. Loaded MCP names are host functions after load_tool_schemas.";
pub const tool_schema =
    \\{"type": "object", "properties": {"code": {"type": "string", "description": "Call-only script, not Python. One statement per line: name = read_file(\"path\") / codedb(\"command\") / bash(\"cmd\") / sleep_ms(ms) / llm_query(\"prompt\") / subagent(\"task\") / loaded mcp__server__tool() or tools.server.tool(); write_file(\"path\", name) saves a bound result; each(arr, tool[, field]) calls tool per item; len(x) and project(x, field) slim it; name = [..] / {..} / \"text\" binds a literal; print(name, ...) is the result. Arguments are string, number, boolean or JSON array/object literals, or bound names. Assignments persist across rlm calls."}}, "required": ["code"]}
;

/// Process-global: on by default. `--old` / `--no-rlm` turn it off; `--rlm`
/// turns it on. Never flipped mid-session. Keep in sync with
/// rlm_spec.available (`sync`) so the SSE path can see it without importing
/// this file (exec.zig would cycle through Agent).
pub var available: bool = true;
/// True after `--rlm` / `--old` / `--no-rlm` so env knobs cannot clobber CLI.
pub var cli_set: bool = false;

pub fn sync() void {
    rlm_spec.available = available;
    rlm_spec.run_host = runHost;
}

/// Last CLI flag wins. Marks `cli_set` so GRAFF_RLM / GRAFF_OLD stay off this path.
pub fn setFromCli(on: bool) void {
    available = on;
    cli_set = true;
    sync();
    if (on) @import("native_fold.zig").showcaseFromCli() else @import("native_fold.zig").resetRlmDiscovery();
}

pub fn resetLive(gpa: Allocator, io: Io) void {
    sync();
    rlm_spec.resetLive(gpa, io);
    rlm_spec.resetBinds(gpa, io);
}

pub fn feedLive(ctx: ToolCtx, delta: []const u8) void {
    sync();
    rlm_spec.feedLive(ctx, delta);
}

/// Append `rlm` after the lean/no-local filters. On by default from turn
/// one (ADR 0140). No-op when `--old` or embedder mode stripped host tools.
pub fn maybeAppend(comptime Spec: type, arena: Allocator, specs: []const Spec) ![]const Spec {
    sync();
    if (!available or no_local_tools.enabled) return specs;
    for (specs) |s| if (std.mem.eql(u8, s.name, tool_name)) return specs;
    const buf = try arena.alloc(Spec, specs.len + 1);
    @memcpy(buf[0..specs.len], specs);
    buf[specs.len] = .{ .name = tool_name, .desc = if (no_local_tools.lean) lean_tool_desc else tool_desc, .schema = tool_schema };
    return buf;
}

pub fn exec(ctx: ToolCtx, input: Value) !ToolOutput {
    sync();
    if (!available) return .{ .text = try ctx.gpa.dupe(u8, "rlm is off — pass --rlm or drop --old"), .is_error = true };
    if (no_local_tools.enabled) return .{ .text = try ctx.gpa.dupe(u8, "rlm is a host tool and is disabled under --no-local-tools"), .is_error = true };
    const code = tools.strField(input, "code") orelse return tools.missingArg(ctx.gpa, "code");
    return runScript(ctx, code);
}

const Binding = rlm_spec.Binding;
const order = @import("rlm_order.zig");

pub fn runScript(ctx: ToolCtx, code: []const u8) !ToolOutput {
    sync();
    var arena_state = std.heap.ArenaAllocator.init(ctx.gpa);
    defer arena_state.deinit();
    const arena = arena_state.allocator();

    var claimed = std.StringHashMap(ToolOutput).init(ctx.gpa);
    defer {
        var cit = claimed.iterator();
        while (cit.next()) |e| ctx.gpa.free(e.value_ptr.text);
        claimed.deinit();
    }
    rlm_spec.takeLive(ctx, &claimed, arena);

    const stmts = try spec_ptc.splitStatements(arena, code);

    var leading: std.ArrayList(spec_ptc.Call) = .empty;
    for (stmts) |stmt| {
        const safe_calls = try order.leading(arena, stmt) orelse break;
        try leading.appendSlice(arena, safe_calls);
    }
    const calls = leading.items;
    try speculate(ctx, arena, calls, &claimed);
    var binds: std.ArrayList(Binding) = .empty;
    try rlm_spec.seedBinds(ctx.gpa, ctx.io, arena, &binds);
    defer rlm_spec.commitBinds(ctx.gpa, ctx.io, binds.items) catch {};
    var printed: std.ArrayList(u8) = .empty;
    defer printed.deinit(ctx.gpa);

    var barrier = false;
    for (stmts) |stmt| {
        if (!barrier and try order.leading(arena, stmt) == null) {
            barrier = true;
            var old = claimed.valueIterator();
            while (old.next()) |out| ctx.gpa.free(out.text);
            claimed.clearRetainingCapacity();
        }
        if (try evalStmt(ctx, arena, stmt, binds.items, &claimed, &printed, &binds)) |err| {
            return err;
        }
    }
    if (printed.items.len == 0) return .{ .text = try ctx.gpa.dupe(u8, "(rlm: script produced no print())") };
    return .{ .text = try printed.toOwnedSlice(ctx.gpa) };
}

fn speculate(ctx: ToolCtx, arena: Allocator, calls: []const spec_ptc.Call, claimed: *std.StringHashMap(ToolOutput)) !void {
    if (calls.len == 0) return;
    var uniq: std.ArrayList(spec_ptc.Call) = .empty;
    var seen = std.StringHashMap(void).init(arena);
    for (calls) |c| {
        const key = try c.key(arena);
        if (claimed.contains(key)) continue;
        if (try seen.fetchPut(key, {})) |_| continue;
        try uniq.append(arena, c);
    }
    if (uniq.items.len == 0) return;
    var read_paths: std.ArrayList([]const u8) = .empty;
    for (uniq.items) |c| {
        if (std.mem.eql(u8, c.name, "read_file")) {
            if (read_miss.pathFromArgsJson(c.args_json)) |p| try read_paths.append(arena, p);
        }
    }
    var batch = read_miss.Batch.init(read_paths.items);
    var wave1: std.ArrayList(spec_ptc.Call) = .empty;
    var hold: std.ArrayList(spec_ptc.Call) = .empty;
    for (uniq.items) |c| {
        if (std.mem.eql(u8, c.name, "read_file")) {
            if (read_miss.pathFromArgsJson(c.args_json)) |p| {
                if (ctx.read_miss) |tracker| {
                    switch (batch.classify(tracker, p)) {
                        .refuse => {
                            try claimed.put(try c.key(arena), .{
                                .text = try read_miss.refusalText(ctx.gpa, p),
                                .is_error = true,
                            });
                            continue;
                        },
                        .hold => {
                            try hold.append(arena, c);
                            continue;
                        },
                        .run => {},
                    }
                }
            }
        }
        try wave1.append(arena, c);
    }
    try launchHost(ctx, arena, wave1.items, claimed);
    if (hold.items.len == 0) return;
    var wave2: std.ArrayList(spec_ptc.Call) = .empty;
    for (hold.items) |c| {
        const p = read_miss.pathFromArgsJson(c.args_json) orelse {
            try wave2.append(arena, c);
            continue;
        };
        if (ctx.read_miss) |tracker| {
            if (tracker.shouldRefuse(p)) {
                try claimed.put(try c.key(arena), .{
                    .text = try read_miss.refusalText(ctx.gpa, p),
                    .is_error = true,
                });
                continue;
            }
        }
        try wave2.append(arena, c);
    }
    try launchHost(ctx, arena, wave2.items, claimed);
}

fn launchHost(ctx: ToolCtx, arena: Allocator, calls: []const spec_ptc.Call, claimed: *std.StringHashMap(ToolOutput)) !void {
    if (calls.len == 0) return;
    const futs = try arena.alloc(Io.Future(ToolOutput), calls.len);
    const keys = try arena.alloc([]const u8, calls.len);
    for (calls, futs, keys) |c, *fut, *key| {
        key.* = try c.key(arena);
        fut.* = ctx.io.async(runHost, .{ ctx, c });
    }
    for (futs, keys, calls) |*fut, key, c| {
        const out = fut.await(ctx.io);
        if (ctx.read_miss) |tracker| tracker.noteOutput(c.name, pathValue(arena, c.args_json), out.text, out.is_error);
        try claimed.put(key, out);
    }
}

fn pathValue(arena: Allocator, args_json: []const u8) Value {
    return std.json.parseFromSliceLeaky(Value, arena, args_json, .{}) catch .null;
}

fn runHost(ctx: ToolCtx, call: spec_ptc.Call) ToolOutput {
    return runHostRaw(ctx, call);
}

fn runHostRaw(ctx: ToolCtx, call: spec_ptc.Call) ToolOutput {
    if (std.mem.eql(u8, call.name, "sleep_ms") or std.mem.eql(u8, call.name, "llm_query")) {
        if (ctx.run_budget) |budget| if (budget.toolRefusal(ctx.gpa, ctx.tracer)) |denied| return denied;
    }
    if (std.mem.eql(u8, call.name, "sleep_ms")) return runSleep(ctx, call.args_json);
    if (std.mem.eql(u8, call.name, "llm_query")) return rlm_query.run(ctx, call.args_json);
    if (std.mem.eql(u8, call.name, "each") or std.mem.eql(u8, call.name, "len") or std.mem.eql(u8, call.name, "project")) {
        return .{ .text = ctx.gpa.dupe(u8, "rlm: each/len/project need binds, not speculation") catch &.{}, .is_error = true };
    }
    var arena_state = std.heap.ArenaAllocator.init(ctx.gpa);
    defer arena_state.deinit();
    const ready = if (rlm_mcp.looksMcp(call.name) or rlm_mcp.resolve(ctx, call.name) != null)
        switch (rlm_mcp.prepare(ctx, arena_state.allocator(), call)) {
            .refuse => |r| return r,
            .run => |c| c,
        }
    else
        call;
    var parsed = std.json.parseFromSlice(Value, ctx.gpa, ready.args_json, .{}) catch {
        return .{ .text = ctx.gpa.dupe(u8, "rlm: bad args") catch &.{}, .is_error = true };
    };
    defer parsed.deinit();
    // #1292: the agent's approval gate, not just the executor's backstops.
    // A denial is an error result, so the script stops here.
    const host_call: tools.ToolCall = .{ .id = if (ctx.host_gate) |gate| gate.call_id else "rlm", .name = ready.name, .input = parsed.value };
    if (ctx.host_gate) |gate| if (gate.check(gate.context, host_call)) |denied| return denied;
    // #1413: schema loading enables catalog calls, not host bindings for
    // agent-managed tools. Their handlers mutate Agent state inline; they
    // cannot run through the pool-thread executor used by RLM.
    if (@import("schema.zig").isMetaName(ready.name)) return .{
        .text = std.fmt.allocPrint(ctx.gpa, "rlm: {s} is agent-managed and is not supported inside rlm; call {s} directly as a structured tool.", .{ ready.name, ready.name }) catch &.{},
        .is_error = true,
    };
    var host_ctx = ctx;
    host_ctx.rlm_host = true;
    return exec_mod.execTool(host_ctx, host_call);
}

fn runSleep(ctx: ToolCtx, args_json: []const u8) ToolOutput {
    var parsed = std.json.parseFromSlice(Value, ctx.gpa, args_json, .{}) catch {
        return .{ .text = ctx.gpa.dupe(u8, "rlm: sleep_ms needs ms") catch &.{}, .is_error = true };
    };
    defer parsed.deinit();
    const ms = tools.intField(parsed.value, "ms") orelse 0;
    const capped: i64 = @min(@max(ms, 0), sleep_cap_ms);
    ctx.io.sleep(.fromMilliseconds(capped), .awake) catch {};
    return .{ .text = sleepText(ctx.gpa, ms, capped) catch ctx.gpa.dupe(u8, "slept") catch &.{} };
}

const sleep_cap_ms: i64 = 5_000;

/// A capped request says so: a model that asked for minutes and read
/// "slept 5000ms" as done has waited 5 seconds, not the pause it narrated.
fn sleepText(gpa: Allocator, requested: i64, slept: i64) ![]u8 {
    if (requested <= slept) return std.fmt.allocPrint(gpa, "slept {d}ms", .{slept});
    return std.fmt.allocPrint(gpa, "slept {d}ms, not the {d}ms requested: sleep_ms is capped at {d}ms and only overlaps short work. To wait for something, use a blocking wait (shell action=output with wait_ms, agent_output) or clock_sleep.", .{ slept, requested, sleep_cap_ms });
}

test "sleepText names the cap when a longer pause was requested" {
    const plain = try sleepText(std.testing.allocator, 40, 40);
    defer std.testing.allocator.free(plain);
    try std.testing.expectEqualStrings("slept 40ms", plain);
    const capped = try sleepText(std.testing.allocator, 300_000, 5_000);
    defer std.testing.allocator.free(capped);
    try std.testing.expect(std.mem.indexOf(u8, capped, "not the 300000ms requested") != null);
    try std.testing.expect(std.mem.indexOf(u8, capped, "clock_sleep") != null);
}

fn evalStmt(
    ctx: ToolCtx,
    arena: Allocator,
    stmt: []const u8,
    binds: []const Binding,
    claimed: *std.StringHashMap(ToolOutput),
    printed: *std.ArrayList(u8),
    bind_out: *std.ArrayList(Binding),
) !?ToolOutput {
    // 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 => {
            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)) {
        .miss => {},
        .ok => return null,
        .fail => |e| return .{ .text = e, .is_error = true },
    }
    const call = try spec_ptc.extractCallBound(arena, stmt, binds);
    if (call) |c| {
        const key = try c.key(arena);
        const cached = claimed.get(key);
        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) });
        } else try echoText(ctx, printed, maybeSlim(arena, out.text)); // ADR 0240: an unbound call prints its result
        return null;
    }
    if (printArgs(stmt)) |inner| {
        var status: ?ToolOutput = null;
        const text = try renderPrint(ctx, arena, inner, binds, claimed, &status);
        if (status) |out| return out;
        if (printed.items.len > 0) try printed.append(ctx.gpa, '\n');
        try printed.appendSlice(ctx.gpa, text);
        return null;
    }
    // ADR 0236: `name = [..]`, `{..}`, a string, a number or another name.
    if (try @import("rlm_literal.zig").assign(arena, stmt, binds)) |b| {
        try bind_out.append(arena, b);
        return null;
    }
    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.";

fn assignName(stmt: []const u8) ?[]const u8 {
    const eq = std.mem.indexOfScalar(u8, stmt, '=') orelse return null;
    const lhs = std.mem.trim(u8, stmt[0..eq], " \t");
    if (lhs.len == 0) return null;
    return lhs;
}

fn printArgs(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];
}

fn renderPrint(ctx: ToolCtx, arena: Allocator, inner: []const u8, binds: []const Binding, claimed: *std.StringHashMap(ToolOutput), status: *?ToolOutput) ![]const u8 {
    const parts = try spec_ptc.splitTopLevel(arena, inner, ',');
    if (parts.len == 0) return "";
    var out: std.ArrayList(u8) = .empty;
    for (parts, 0..) |part, i| {
        if (i > 0) try out.append(arena, '\n');
        try out.appendSlice(arena, try renderPrintPart(ctx, arena, part, binds, claimed, status));
        if (status.* != null) break;
    }
    return out.toOwnedSlice(arena);
}

fn renderPrintPart(ctx: ToolCtx, arena: Allocator, inner: []const u8, binds: []const Binding, claimed: *std.StringHashMap(ToolOutput), status: *?ToolOutput) ![]const u8 {
    const t = std.mem.trim(u8, inner, " \t");
    if (t.len >= 2 and (t[0] == '"' or t[0] == '\'') and t[t.len - 1] == t[0]) return t[1 .. t.len - 1];
    if (rlm_reduce.evalExpr(arena, t, binds)) |text| return maybeSlim(arena, text) else |err| if (err != error.Miss) {
        status.* = .{ .text = try rlm_reduce.failText(ctx.gpa, t, err), .is_error = true };
        return "";
    }
    var i = binds.len;
    while (i > 0) {
        i -= 1;
        const name = binds[i].name;
        if (std.mem.eql(u8, name, t)) return maybeSlim(arena, binds[i].text);
        if (std.mem.startsWith(u8, t, name) and t.len > name.len and
            (t[name.len] == '[' or t[name.len] == '.')) return unsupportedPrint(ctx, status);
    }
    if (try spec_ptc.extractCallBound(arena, t, binds)) |c| {
        const key = try c.key(arena);
        const cached = claimed.get(key);
        const out = cached orelse runHost(ctx, c);
        defer if (cached == null) ctx.gpa.free(out.text);
        if (order.stopped(out)) {
            status.* = try order.copy(ctx.gpa, out);
            return "";
        }
        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
    // unevaluated expression is a successful tool result.
    if (t.len == 0) return unsupportedPrint(ctx, status);
    for (t) |c| if (!std.ascii.isAlphanumeric(c) and c != '_') return unsupportedPrint(ctx, status);
    return try arena.dupe(u8, t);
}

fn unsupportedPrint(ctx: ToolCtx, status: *?ToolOutput) ![]const u8 {
    status.* = .{ .text = try ctx.gpa.dupe(u8, "rlm: unsupported print expression; host results are text, so assign then print(name)."), .is_error = true };
    return "";
}

fn maybeSlim(arena: Allocator, payload: []const u8) []const u8 {
    const cut = mcp_shapes.slim(arena, payload) orelse return payload;
    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. 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;
}