Skip to content

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

Python
6.5 KB
Raw Blame
//! What the user allows, and what agents did. Stopped refuses everything;
//! input (clicks, keys, launching) is refused until the user turns it on;
//! the whole screen (the real pointer and keyboard, pictures of the display)
//! is refused until they turn that on too, so by default agents stay inside
//! one app; nanocua's own windows are never acted on (an agent can't press
//! its own Resume). Every call is logged: what, with what, and how it went.
const std = @import("std");
const tools = @import("tools.zig");

pub const Policy = struct {
    /// The kill switch: nothing runs until the user resumes.
    stopped: bool = false,
    /// Clicks, keys, scrolling, launching apps.
    allow_input: bool = false,
    /// The real pointer and keyboard, and pictures of the whole display.
    allow_whole_screen: bool = false,

    /// Why `tool` may not run now, or null if it may. `whole_screen`: the
    /// call asked for more than one app.
    pub fn denial(p: Policy, tool: tools.Tool, whole_screen: bool) ?[]const u8 {
        if (p.stopped) return "nanocua is stopped: the user pressed Stop. Wait for them to resume it.";
        if (tool.kind() == .act and !p.allow_input)
            return "Input is off in nanocua: you may look (list_apps, get_ui_tree, screenshot) but not act. Ask the user to turn on \"Allow input\".";
        if (whole_screen and !p.allow_whole_screen and tool != .list_apps and tool != .get_ui_tree)
            return "The whole screen is off in nanocua: work inside one app (leave out whole_screen). If that can't work, ask the user to turn on \"Allow whole screen\".";
        return null;
    }
};

pub const Status = enum { running, ok, failed, denied };

pub const Entry = struct {
    seq: u64,
    tool: tools.Tool,
    status: Status = .running,
    /// When it started, by the hub's clock; how long it took.
    at: f64,
    ms: f32 = 0,
    summary_buf: [96]u8 = undefined,
    summary_len: u8 = 0,
    detail_buf: [120]u8 = undefined,
    detail_len: u8 = 0,

    pub fn summary(e: *const Entry) []const u8 {
        return e.summary_buf[0..e.summary_len];
    }

    pub fn detail(e: *const Entry) []const u8 {
        return e.detail_buf[0..e.detail_len];
    }
};

/// The last `capacity` calls, newest last.
pub const Log = struct {
    pub const capacity = 200;
    entries: [capacity]Entry = undefined,
    len: usize = 0,
    /// Where the oldest entry is once the ring is full.
    head: usize = 0,
    next_seq: u64 = 1,
    /// Counts since launch.
    calls: u64 = 0,
    denied: u64 = 0,

    pub fn add(l: *Log, tool: tools.Tool, summary: []const u8, at: f64) u64 {
        const e: Entry = .{ .seq = l.next_seq, .tool = tool, .at = at };
        l.next_seq += 1;
        l.calls += 1;
        const slot = if (l.len < capacity) blk: {
            l.len += 1;
            break :blk l.len - 1;
        } else blk: {
            const s = l.head;
            l.head = (l.head + 1) % capacity;
            break :blk s;
        };
        l.entries[slot] = e;
        const n = clip(&l.entries[slot].summary_buf, summary);
        l.entries[slot].summary_len = @intCast(n);
        return e.seq;
    }

    pub fn finish(l: *Log, seq: u64, status: Status, detail: []const u8, now: f64) void {
        const e = l.find(seq) orelse return;
        e.status = status;
        if (status == .denied) l.denied += 1;
        e.ms = @floatCast(@max(0, (now - e.at) * 1000));
        e.detail_len = @intCast(clip(&e.detail_buf, detail));
    }

    pub fn find(l: *Log, seq: u64) ?*Entry {
        for (l.entries[0..l.len]) |*e| if (e.seq == seq) return e;
        return null;
    }

    /// The `i`th newest entry (0 is the newest).
    pub fn newest(l: *Log, i: usize) ?*const Entry {
        if (i >= l.len) return null;
        const oldest_first = l.len - 1 - i;
        return &l.entries[(l.head + oldest_first) % l.len];
    }

    pub fn clear(l: *Log) void {
        l.len = 0;
        l.head = 0;
    }
};

/// Copies `s` into `buf`, cut at a character's start with "…" when long,
/// on one line.
fn clip(buf: []u8, s: []const u8) usize {
    const ell = "…";
    var n = s.len;
    var cut = false;
    if (n > buf.len) {
        n = buf.len - ell.len;
        while (n > 0 and (s[n] & 0xc0) == 0x80) n -= 1;
        cut = true;
    }
    for (s[0..n], 0..) |ch, i| buf[i] = if (ch == '\n' or ch == '\r' or ch == '\t') ' ' else ch;
    if (cut) {
        @memcpy(buf[n..][0..ell.len], ell);
        n += ell.len;
    }
    return n;
}

test "stopped refuses everything; input waits for the user" {
    var p: Policy = .{};
    try std.testing.expect(p.denial(.get_ui_tree, false) == null);
    try std.testing.expect(p.denial(.click, false) != null);
    p.allow_input = true;
    try std.testing.expect(p.denial(.click, false) == null);
    p.stopped = true;
    try std.testing.expect(p.denial(.screenshot, false) != null);
    try std.testing.expect(p.denial(.click, false) != null);
}

test "the whole screen waits for the user, one app doesn't" {
    var p: Policy = .{ .allow_input = true };
    try std.testing.expect(p.denial(.screenshot, false) == null);
    try std.testing.expect(p.denial(.click, false) == null);
    try std.testing.expect(p.denial(.screenshot, true) != null);
    try std.testing.expect(p.denial(.click, true) != null);
    try std.testing.expect(p.denial(.press_key, true) != null);
    try std.testing.expect(p.denial(.get_ui_tree, true) == null); // reading an app is one app anyway
    p.allow_whole_screen = true;
    try std.testing.expect(p.denial(.screenshot, true) == null);
    try std.testing.expect(p.denial(.click, true) == null);
    p.allow_input = false;
    try std.testing.expect(p.denial(.click, true) != null); // input stays its own switch
}

test "the log keeps the newest calls, clipped to a line" {
    var l: Log = .{};
    const first = l.add(.click, "a\nb", 1);
    l.finish(first, .ok, "pressed", 1.25);
    try std.testing.expectEqualStrings("a b", l.newest(0).?.summary());
    try std.testing.expectEqual(@as(f32, 250), l.newest(0).?.ms);
    const long: [200]u8 = @splat('x');
    for (0..Log.capacity + 5) |i| _ = l.add(.scroll, &long, @floatFromInt(i));
    try std.testing.expectEqual(@as(usize, Log.capacity), l.len);
    try std.testing.expect(l.find(first) == null);
    const e = l.newest(0).?;
    try std.testing.expectEqual(l.next_seq - 1, e.seq);
    try std.testing.expect(std.mem.endsWith(u8, e.summary(), "…"));
    try std.testing.expect(e.summary().len <= 96);
    try std.testing.expectEqual(l.next_seq - Log.capacity, l.newest(Log.capacity - 1).?.seq);
}