Skip to content

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

Python
12.0 KB
Raw Blame
//! ADR 0246: Jev in the flow. When a root turn starts on an eligible model,
//! graff asks Jev for the turn's reasoning effort itself; the model was offered
//! the jev_effort tool and never called it. The request runs alongside the
//! turn's first model call, so it adds no wait: its pick applies from the
//! turn's next request (agent_request.zig applies pending picks there). Jev
//! sees a summary built here: the request's words with code, paths, file
//! names, URLs, emails, identifiers and number-heavy or long tokens dropped.
//! The pick holds for that turn only and is never saved, an effort the user
//! chose (anything but the session default) is never overridden, and a pick
//! still in flight when the turn ends is canceled and dropped.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const ReasoningEffort = @import("main.zig").ReasoningEffort;
const jev_tool = @import("jev_tool.zig");

/// GRAFF_JEV_AUTO=0 (or off/false/no) turns the per-turn selection off.
pub var enabled: bool = true;
/// How long a turn waits for Jev before it goes ahead at the default effort.
pub const timeout_ms: u32 = 4_000;
pub const max_summary = 280;

/// jev_tool.configure passes GRAFF_JEV_AUTO's value.
pub fn setEnabled(value: ?[]const u8) void {
    const v = value orelse "";
    enabled = !(std.mem.eql(u8, v, "0") or std.ascii.eqlIgnoreCase(v, "off") or
        std.ascii.eqlIgnoreCase(v, "false") or std.ascii.eqlIgnoreCase(v, "no"));
}

/// The words Jev may see: no code, paths, file names, URLs, emails,
/// identifiers, ids or long tokens. Empty when nothing safe is left.
pub fn summary(arena: Allocator, prompt: []const u8) ![]const u8 {
    var out: std.ArrayList(u8) = .empty;
    var in_fence = false;
    var lines = std.mem.splitScalar(u8, prompt, '\n');
    while (lines.next()) |line| {
        const t = std.mem.trim(u8, line, " \t\r");
        if (std.mem.startsWith(u8, t, "```")) {
            in_fence = !in_fence;
            continue;
        }
        if (in_fence) continue;
        var words = std.mem.tokenizeAny(u8, t, " \t");
        while (words.next()) |w| {
            if (!keep(w)) continue;
            if (out.items.len + w.len + 1 > max_summary) return out.items;
            if (out.items.len != 0) try out.append(arena, ' ');
            try out.appendSlice(arena, w);
        }
    }
    return out.items;
}

fn keep(w: []const u8) bool {
    if (w.len > 24) return false; // keys, hashes, long identifiers
    if (std.mem.indexOfAny(u8, w, "/\\`@<>{}[]=$|_#~") != null) return false; // paths, code, emails, markup, identifiers
    var digits: usize = 0;
    for (w) |c| digits += @intFromBool(std.ascii.isDigit(c));
    if (digits >= 4) return false; // ids and numbers that identify something
    const core = std.mem.trimEnd(u8, w, ".,;:!?)\"'");
    if (std.mem.lastIndexOfScalar(u8, core, '.')) |dot| if (dot > 0 and dot + 1 < core.len) return false; // file.ext, a.b.c
    return true;
}

fn lastUserText(agent: anytype) ?[]const u8 {
    const items = agent.messages.items;
    var i = items.len;
    while (i > 0) {
        i -= 1;
        const m = items[i];
        if (m != .object) continue;
        const role = m.object.get("role") orelse continue;
        if (role != .string or !std.mem.eql(u8, role.string, "user")) continue;
        if (m.object.get(@import("session_wake.zig").origin_key) != null) return null; // a harness message, not a request
        const content = m.object.get("content") orelse return null;
        switch (content) {
            .string => |s| return s,
            .array => |parts| for (parts.items) |part| {
                if (part != .object) continue;
                const text = part.object.get("text") orelse continue;
                if (text == .string and text.string.len != 0) return text.string;
            },
            else => {},
        }
        return null;
    }
    return null;
}

/// Start this turn's pick alongside its first request. Root turns at the
/// session default only; never blocks.
pub fn beginTurn(agent: anytype) void {
    const pending = &agent.jev_effort_pending;
    pending.auto = .{};
    if (!enabled or agent.sub or agent.reasoning != .medium) return;
    if (!jev_tool.available(agent.provider)) return;
    const prompt = lastUserText(agent) orelse return;
    var scratch = std.heap.ArenaAllocator.init(agent.gpa);
    defer scratch.deinit();
    const task = summary(scratch.allocator(), prompt) catch return;
    if (task.len == 0) return;
    const owned = agent.gpa.dupe(u8, task) catch return;
    const token = pending.beginTurn(agent.io, agent.provider) orelse {
        agent.gpa.free(owned);
        return;
    };
    pending.auto.task = owned;
    pending.auto.saved = agent.reasoning;
    pending.auto.future = agent.io.concurrent(pickTask, .{ agent.gpa, agent.io, agent.client, agent.provider, owned, pending, token }) catch {
        pending.abort(agent.io, token);
        agent.gpa.free(owned);
        pending.auto = .{};
        return;
    };
}

fn pickTask(gpa: Allocator, io: Io, client: *std.http.Client, provider: @import("provider.zig").Provider, task: []const u8, pending: *@import("jev_effort_state.zig").Pending, token: u64) void {
    const t0 = Io.Timestamp.now(io, .awake).nanoseconds;
    const chosen = jev_tool.chooseForTurn(gpa, io, client, provider, task, timeout_ms);
    const ms = @divTrunc(Io.Timestamp.now(io, .awake).nanoseconds - t0, std.time.ns_per_ms);
    pending.auto.ms.store(@intCast(std.math.clamp(ms, 0, std.math.maxInt(u32))), .release);
    if (chosen) |effort| {
        pending.auto.picked = effort;
        _ = pending.commit(io, token, effort);
        pending.auto.outcome.store(1, .release);
    } else {
        pending.abort(io, token);
        pending.auto.outcome.store(2, .release);
    }
}

/// Cancel a pick still in flight, drop one no request applied, and put the
/// session effort back unless someone changed it during the turn.
pub fn endTurn(agent: anytype) void {
    const pending = &agent.jev_effort_pending;
    if (pending.auto.future == null and pending.auto.saved == null) return;
    if (pending.auto.future) |*f| f.cancel(agent.io);
    pending.dropTurn(agent.io);
    if (pending.auto.applied) |a| if (agent.reasoning == a) {
        if (pending.auto.saved) |s| agent.reasoning = s;
    };
    if (agent.tracer) |tr| {
        var buf: [96]u8 = undefined;
        const outcome = pending.auto.outcome.load(.acquire);
        const line = std.fmt.bufPrint(&buf, "turn effort {s} in {d}ms{s}", .{
            if (outcome == 1) @tagName(pending.auto.picked) else "unavailable",
            pending.auto.ms.load(.acquire),
            if (outcome == 1 and pending.auto.applied == null) " (late, dropped)" else "",
        }) catch "turn effort";
        tr.note("jev", line);
    }
    if (pending.auto.task.len != 0) agent.gpa.free(pending.auto.task);
    pending.auto = .{};
}

test "ADR 0246: the summary keeps the request's words and drops what could identify the work" {
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    try std.testing.expectEqualStrings("Fix the failing test in and run", try summary(a, "Fix the failing test in src/app/main.py and run `pytest -q`."));
    try std.testing.expectEqualStrings("Count the errors per service, then write", try summary(a, "Count the errors per service, then write summary.json\n```python\nsecret = 'sk-live-1234'\n```"));
    try std.testing.expectEqualStrings("Email about the outage", try summary(a, "Email [email protected] about https://status.example.com the outage"));
    try std.testing.expectEqualStrings("Rename to in every caller", try summary(a, "Rename get_user to fetch_user in every caller"));
    try std.testing.expectEqualStrings("Close issue as done.", try summary(a, "Close issue 48213 as done."));
    try std.testing.expectEqualStrings("", try summary(a, "ghp_0123456789abcdefghijklmnopqrstuvwxyz"));
    var long: std.ArrayList(u8) = .empty;
    for (0..100) |_| try long.appendSlice(a, "word ");
    const cut = try summary(a, long.items);
    try std.testing.expect(cut.len <= max_summary and cut.len > max_summary - 10);
}

const TestAgent = struct {
    gpa: Allocator,
    io: Io,
    client: *std.http.Client,
    provider: @import("provider.zig").Provider,
    reasoning: ReasoningEffort = .medium,
    sub: bool = false,
    fast: bool = false,
    ultracode_mode: bool = false,
    show_thinking: bool = false,
    ai_title: bool = false,
    messages: std.json.Array,
    tracer: ?*@import("trace.zig").Tracer = null,
    jev_effort_pending: @import("jev_effort_state.zig").Pending = .{},
};

fn testAgent(arena: Allocator, client: *std.http.Client, prompt: []const u8) !TestAgent {
    var messages = std.json.Array.init(arena);
    var user: std.json.ObjectMap = .empty;
    try user.put(arena, "role", .{ .string = "user" });
    try user.put(arena, "content", .{ .string = prompt });
    try messages.append(.{ .object = user });
    return .{ .gpa = std.testing.allocator, .io = std.testing.io, .client = client, .messages = messages, .provider = .{ .id = "chatgpt-new", .kind = .responses, .auth = .bearer, .url = "", .api_key = "", .model = "gpt-6.1-sol", .context = 272_000 } };
}

fn waitPick(agent: *TestAgent) void {
    if (agent.jev_effort_pending.auto.future) |*f| f.await(agent.io);
}

test "ADR 0246: the pick runs alongside the turn, applies at the next request, and the turn's end puts the default back" {
    const Env = struct {
        mode: []const u8,
        pub fn get(self: @This(), key: []const u8) ?[]const u8 {
            return if (std.mem.eql(u8, key, "JEV_BACKEND")) self.mode else null;
        }
    };
    jev_tool.configure(Env{ .mode = "mock" });
    defer jev_tool.configure(Env{ .mode = "" });
    _ = jev_tool.setCodegraffLoginKey(std.testing.io, "synthetic-login");
    defer _ = jev_tool.setCodegraffLoginKey(std.testing.io, null);
    const state = @import("jev_effort_state.zig");
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var client: std.http.Client = undefined;

    // beginTurn returns before the pick lands: the first request runs at the default.
    var agent = try testAgent(arena_state.allocator(), &client, "Refactor the session store and keep the tests green");
    beginTurn(&agent);
    try std.testing.expectEqual(ReasoningEffort.medium, agent.reasoning);
    waitPick(&agent);
    state.apply(&agent); // the next request boundary
    try std.testing.expectEqual(ReasoningEffort.high, agent.reasoning); // the mock answers high
    endTurn(&agent);
    try std.testing.expectEqual(ReasoningEffort.medium, agent.reasoning);

    // A pick no request applied is dropped at the turn's end, not applied or saved.
    var late = try testAgent(arena_state.allocator(), &client, "Refactor the session store");
    beginTurn(&late);
    waitPick(&late);
    endTurn(&late);
    try std.testing.expectEqual(ReasoningEffort.medium, late.reasoning);
    state.apply(&late);
    try std.testing.expectEqual(ReasoningEffort.medium, late.reasoning);

    // An effort changed during the turn stays.
    var changed = try testAgent(arena_state.allocator(), &client, "Refactor the session store");
    beginTurn(&changed);
    waitPick(&changed);
    state.apply(&changed);
    changed.reasoning = .xhigh;
    endTurn(&changed);
    try std.testing.expectEqual(ReasoningEffort.xhigh, changed.reasoning);

    // A user-chosen effort, a subagent, and the off switch start no pick.
    var pinned = try testAgent(arena_state.allocator(), &client, "Refactor the session store");
    pinned.reasoning = .low;
    beginTurn(&pinned);
    try std.testing.expect(pinned.jev_effort_pending.auto.future == null);
    var child = try testAgent(arena_state.allocator(), &client, "Refactor the session store");
    child.sub = true;
    beginTurn(&child);
    try std.testing.expect(child.jev_effort_pending.auto.future == null);
    defer enabled = true;
    setEnabled("0");
    var off = try testAgent(arena_state.allocator(), &client, "Refactor the session store");
    beginTurn(&off);
    try std.testing.expect(off.jev_effort_pending.auto.future == null);
}