Skip to content

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

Python
14.0 KB
Raw Blame
//! MCP over newline-delimited JSON-RPC: initialize, ping, tools/list and
//! tools/call. The hub checks each call against the policy, logs it, and
//! hands it to the backend with a Reply, which the backend completes now
//! or later (a screenshot finishes on another queue), on the main thread.
//! Connections are numbers: a reply to one that closed is dropped.
const std = @import("std");
const tools = @import("tools.zig");
const policy = @import("policy.zig");

pub const protocol_version = "2025-06-18";
pub const version = "0.1.0";

/// Where replies go: the server's connection `conn`, one line each.
pub const Sink = struct {
    ptr: *anyopaque,
    send: *const fn (ptr: *anyopaque, conn: u64, line: []const u8) void,
};

/// What runs the tools. `call` copies what it needs from `args` before
/// returning; it completes `reply` exactly once, now or later.
pub const Backend = struct {
    ptr: *anyopaque,
    call: *const fn (ptr: *anyopaque, tool: tools.Tool, args: tools.Args, reply: *Reply) void,
    /// A connection went away: what it held can go too.
    closed: ?*const fn (ptr: *anyopaque, conn: u64) void = null,
};

/// The switches, for `nanocua/*` calls (control.zig). `id` lasts only the call.
pub const Control = struct {
    ptr: *anyopaque,
    func: *const fn (ptr: *anyopaque, conn: u64, id: []const u8, method: []const u8, params: ?std.json.Value) void,
};

pub const Content = union(enum) {
    text: []const u8,
    /// Base64 already.
    image: struct { data: []const u8, mime: []const u8 },
};

pub const Callback = struct {
    ptr: *anyopaque,
    func: *const fn (ptr: *anyopaque) void,
};

pub const Hub = struct {
    gpa: std.mem.Allocator,
    sink: Sink,
    backend: Backend,
    policy: policy.Policy = .{},
    log: policy.Log = .{},
    /// Seconds, for the log.
    clock: *const fn () f64,
    /// Something changed for the panel (a call came or finished).
    changed: ?Callback = null,
    /// Calls not yet answered.
    pending: usize = 0,
    /// Null where nothing can answer them (`nanocua mcp`'s own hub): agents
    /// reach the switches only by opening the socket themselves.
    control: ?Control = null,

    pub fn closed(h: *Hub, conn: u64) void {
        if (h.backend.closed) |f| f(h.backend.ptr, conn);
    }

    /// Handles one line from connection `conn`.
    pub fn handle(h: *Hub, conn: u64, line: []const u8) void {
        if (std.mem.trim(u8, line, " \t\r\n").len == 0) return;
        var arena: std.heap.ArenaAllocator = .init(h.gpa);
        defer arena.deinit();
        const a = arena.allocator();
        const msg = std.json.parseFromSliceLeaky(std.json.Value, a, line, .{}) catch
            return h.sendError(conn, "null", -32700, "Parse error");
        if (msg != .object) return h.sendError(conn, "null", -32600, "Invalid request");
        const id_v = msg.object.get("id");
        const method_v = msg.object.get("method") orelse return; // a response: nothing asked
        if (method_v != .string) return h.sendError(conn, "null", -32600, "Invalid request");
        // Notifications (initialized, cancelled) need no answer.
        const id_val = id_v orelse return;
        const id = std.json.Stringify.valueAlloc(a, id_val, .{}) catch return;
        const method = method_v.string;
        const params = msg.object.get("params");
        if (std.mem.eql(u8, method, "initialize")) {
            h.sendResult(conn, id, initResult(a, params) catch return);
        } else if (std.mem.eql(u8, method, "ping")) {
            h.sendResult(conn, id, "{}");
        } else if (std.mem.eql(u8, method, "tools/list")) {
            var aw: std.Io.Writer.Allocating = .init(a);
            tools.writeList(&aw.writer) catch return;
            h.sendResult(conn, id, aw.written());
        } else if (std.mem.eql(u8, method, "tools/call")) {
            h.call(conn, id, params);
        } else if (std.mem.startsWith(u8, method, "nanocua/") and h.control != null) {
            h.control.?.func(h.control.?.ptr, conn, id, method, params);
        } else h.sendError(conn, id, -32601, "Method not found");
    }

    fn call(h: *Hub, conn: u64, id: []const u8, params: ?std.json.Value) void {
        const p = tools.Args.of(params);
        const name = p.string("name") orelse return h.sendError(conn, id, -32602, "tools/call needs a name");
        const tool = tools.Tool.parse(name) orelse return h.sendError(conn, id, -32602, "Unknown tool");
        const args_v: ?std.json.Value = if (p.obj) |o| o.get("arguments") else null;
        var sum_buf: [256]u8 = undefined;
        const sum = summarize(&sum_buf, args_v);
        const seq = h.log.add(tool, sum, h.clock());
        const reply = h.gpa.create(Reply) catch return;
        reply.* = .{ .hub = h, .conn = conn, .seq = seq, .id = h.gpa.dupe(u8, id) catch {
            h.gpa.destroy(reply);
            return;
        } };
        h.pending += 1;
        h.notify();
        const whole_screen = tools.Args.of(args_v).boolean("whole_screen") orelse false;
        if (h.policy.denial(tool, whole_screen)) |why| return reply.finish(&.{.{ .text = why }}, true, .denied);
        h.backend.call(h.backend.ptr, tool, tools.Args.of(args_v), reply);
    }

    fn notify(h: *Hub) void {
        if (h.changed) |c| c.func(c.ptr);
    }

    pub fn sendResult(h: *Hub, conn: u64, id: []const u8, result: []const u8) void {
        var aw: std.Io.Writer.Allocating = .init(h.gpa);
        defer aw.deinit();
        aw.writer.print("{{\"jsonrpc\":\"2.0\",\"id\":{s},\"result\":{s}}}", .{ id, result }) catch return;
        h.sink.send(h.sink.ptr, conn, aw.written());
    }

    pub fn sendError(h: *Hub, conn: u64, id: []const u8, code: i32, message: []const u8) void {
        var buf: [256]u8 = undefined;
        const line = std.fmt.bufPrint(&buf, "{{\"jsonrpc\":\"2.0\",\"id\":{s},\"error\":{{\"code\":{d},\"message\":\"{s}\"}}}}", .{ id, code, message }) catch return;
        h.sink.send(h.sink.ptr, conn, line);
    }
};

/// An unanswered tools/call; frees itself once finished.
pub const Reply = struct {
    hub: *Hub,
    conn: u64,
    id: []u8,
    seq: u64,

    pub fn text(r: *Reply, s: []const u8) void {
        r.finish(&.{.{ .text = s }}, false, .ok);
    }

    /// A failure the model should read (no permission, no such element).
    pub fn fail(r: *Reply, s: []const u8) void {
        r.finish(&.{.{ .text = s }}, true, .failed);
    }

    pub fn failf(r: *Reply, comptime fmt: []const u8, args: anytype) void {
        var buf: [512]u8 = undefined;
        r.fail(std.fmt.bufPrint(&buf, fmt, args) catch fmt);
    }

    pub fn textf(r: *Reply, comptime fmt: []const u8, args: anytype) void {
        var buf: [512]u8 = undefined;
        r.text(std.fmt.bufPrint(&buf, fmt, args) catch fmt);
    }

    pub fn finish(r: *Reply, content: []const Content, is_error: bool, status: policy.Status) void {
        const h = r.hub;
        defer {
            h.pending -= 1;
            h.gpa.free(r.id);
            h.gpa.destroy(r);
            h.notify();
        }
        var detail: []const u8 = "";
        for (content) |c| if (c == .text) {
            detail = c.text;
            break;
        } else {
            detail = "image";
        };
        h.log.finish(r.seq, status, detail, h.clock());
        var aw: std.Io.Writer.Allocating = .init(h.gpa);
        defer aw.deinit();
        writeResult(&aw.writer, r.id, content, is_error) catch return;
        h.sink.send(h.sink.ptr, r.conn, aw.written());
    }
};

/// One tools/call result as a JSON-RPC line, without a Reply.
pub fn writeResult(w: *std.Io.Writer, id: []const u8, content: []const Content, is_error: bool) !void {
    try w.print("{{\"jsonrpc\":\"2.0\",\"id\":{s},\"result\":{{\"content\":[", .{id});
    for (content, 0..) |c, i| {
        if (i > 0) try w.writeByte(',');
        switch (c) {
            .text => |t| {
                try w.writeAll("{\"type\":\"text\",\"text\":");
                try std.json.Stringify.encodeJsonString(t, .{}, w);
                try w.writeByte('}');
            },
            .image => |img| try w.print("{{\"type\":\"image\",\"data\":\"{s}\",\"mimeType\":\"{s}\"}}", .{ img.data, img.mime }),
        }
    }
    try w.print("],\"isError\":{}}}}}", .{is_error});
}

fn initResult(a: std.mem.Allocator, params: ?std.json.Value) ![]const u8 {
    // Answer in the client's version when it asks for one we know.
    const known = [_][]const u8{ "2024-11-05", "2025-03-26", "2025-06-18" };
    var ver: []const u8 = protocol_version;
    if (tools.Args.of(params).string("protocolVersion")) |v| for (known) |k| {
        if (std.mem.eql(u8, v, k)) ver = k;
    };
    var aw: std.Io.Writer.Allocating = .init(a);
    try aw.writer.print("{{\"protocolVersion\":\"{s}\",\"capabilities\":{{\"tools\":{{\"listChanged\":false}}}},\"serverInfo\":{{\"name\":\"nanocua\",\"version\":\"{s}\"}},\"instructions\":", .{ ver, version });
    try std.json.Stringify.encodeJsonString(instructions, .{}, &aw.writer);
    try aw.writer.writeByte('}');
    return aw.written();
}

pub const instructions =
    \\nanocua lets you use apps on this computer, within what its user allows in the nanocua window.
    \\Use it for another app's real UI; to show or test your own work, prefer the project's own commands.
    \\You work inside one app in the background: the user's pointer and keyboard stay theirs. Look first:
    \\get_ui_tree gives exact elements with refs and makes that app the one you act in; act on refs (click,
    \\type_text, set_value). Use screenshot when the tree is not enough. Coordinates are screen points from
    \\the top-left. If a call says nanocua is stopped, or input or the whole screen is off, tell the user
    \\once and carry on without it; do not retry in a loop, and permissions are the user's to give.
;

/// The arguments as one short line for the log.
fn summarize(buf: []u8, args: ?std.json.Value) []const u8 {
    const v = args orelse return "";
    var w: std.Io.Writer = .fixed(buf);
    std.json.Stringify.value(v, .{}, &w) catch {};
    const s = w.buffered();
    if (std.mem.eql(u8, s, "{}")) return "";
    return s;
}

const testing = std.testing;

/// Lines sent, for the tests.
const Lines = struct {
    gpa: std.mem.Allocator,
    list: std.ArrayList(u8) = .empty,
    fn send(ptr: *anyopaque, conn: u64, line: []const u8) void {
        const l: *Lines = @ptrCast(@alignCast(ptr));
        l.list.print(l.gpa, "{d}:{s}\n", .{ conn, line }) catch {};
    }
};

/// Answers clicks at once and keeps screenshots waiting, as the real one.
const Fake = struct {
    held: ?*Reply = null,
    fn call(ptr: *anyopaque, tool: tools.Tool, args: tools.Args, reply: *Reply) void {
        const f: *Fake = @ptrCast(@alignCast(ptr));
        switch (tool) {
            .screenshot => f.held = reply,
            .click => if (args.point()) |p| reply.textf("clicked {d},{d}", .{ p[0], p[1] }) else reply.fail("no target"),
            else => reply.text("ok"),
        }
    }
};

fn zero() f64 {
    return 0;
}

test "a session: initialize, list, calls answered now and later, the policy" {
    var lines: Lines = .{ .gpa = testing.allocator };
    defer lines.list.deinit(testing.allocator);
    var fake: Fake = .{};
    var h: Hub = .{ .gpa = testing.allocator, .clock = zero, .sink = .{ .ptr = &lines, .send = Lines.send }, .backend = .{ .ptr = &fake, .call = Fake.call } };
    h.handle(1, "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\"}}");
    h.handle(1, "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}");
    h.handle(1, "{\"jsonrpc\":\"2.0\",\"id\":\"two\",\"method\":\"tools/list\"}");
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "\"protocolVersion\":\"2025-03-26\"") != null);
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "1:{\"jsonrpc\":\"2.0\",\"id\":\"two\",\"result\":{\"tools\":[") != null);
    lines.list.clearRetainingCapacity();

    // Input is off: the click is refused, and logged as such.
    h.handle(2, "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"click\",\"arguments\":{\"x\":5,\"y\":6}}}");
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "\"isError\":true") != null);
    try testing.expectEqual(policy.Status.denied, h.log.newest(0).?.status);
    try testing.expectEqualStrings("{\"x\":5,\"y\":6}", h.log.newest(0).?.summary());
    h.policy.allow_input = true;
    lines.list.clearRetainingCapacity();
    h.handle(2, "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"click\",\"arguments\":{\"x\":5,\"y\":6}}}");
    try testing.expectEqualStrings("2:{\"jsonrpc\":\"2.0\",\"id\":4,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"clicked 5,6\"}],\"isError\":false}}\n", lines.list.items);

    // A screenshot answers later; the hub counts it until then.
    lines.list.clearRetainingCapacity();
    h.handle(2, "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"screenshot\"}}");
    try testing.expectEqual(@as(usize, 1), h.pending);
    try testing.expectEqual(@as(usize, 0), lines.list.items.len);
    fake.held.?.finish(&.{ .{ .image = .{ .data = "QUJD", .mime = "image/jpeg" } }, .{ .text = "1:1" } }, false, .ok);
    try testing.expectEqual(@as(usize, 0), h.pending);
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "{\"type\":\"image\",\"data\":\"QUJD\",\"mimeType\":\"image/jpeg\"}") != null);

    // Errors: bad JSON, unknown methods and tools.
    lines.list.clearRetainingCapacity();
    h.handle(3, "{nope");
    h.handle(3, "{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"resources/list\"}");
    h.handle(3, "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"rm_rf\"}}");
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "-32700") != null);
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "-32601") != null);
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "-32602") != null);

    // Stopped: even looking is refused.
    h.policy.stopped = true;
    lines.list.clearRetainingCapacity();
    h.handle(3, "{\"jsonrpc\":\"2.0\",\"id\":8,\"method\":\"tools/call\",\"params\":{\"name\":\"list_apps\"}}");
    try testing.expect(std.mem.indexOf(u8, lines.list.items, "stopped") != null);
}