Skip to content

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

Python
19.0 KB
Raw Blame
//! The durable side of `graff serve` (#330 part 2): a per-session append-only
//! log of the exact protocol event lines the bridge forwarded, plus the replay
//! filter and the line helpers serve.zig reads events with.
//!
//! Why a second file rather than the existing `.graff/traces/<run>.jsonl`: the
//! trace stream is per-PROCESS performance telemetry keyed by run id, and it
//! does not contain protocol events at all — nothing in it can reconstruct the
//! `--json` stream a supervisor lost. The conversation itself is NOT duplicated
//! here; that stays in `.graff/sessions/<name>.session.json`, which the child
//! already autosaves after every turn and `--resume <name>` already restores.
//! This log is only the event tape, keyed by the same session name, so a
//! REPLACEMENT serve process appends to the very file the dead one was writing
//! and `?from=N` keeps meaning the same thing across the process boundary.

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

const protocol_seq = @import("protocol_seq.zig");

pub const serve_dir = ".graff/serve";
/// The producer stamps `seq`; the bridge only reads it back off the line.
pub const seqOf = protocol_seq.seqOf;
/// Cap on a whole event log we are willing to slurp for a cold replay. Well
/// past a realistic session; a bigger file replays nothing rather than trying
/// to buy the memory.
pub const max_log_bytes = 64 * 1024 * 1024;

pub fn logPath(allocator: Allocator, name: []const u8) Allocator.Error![]const u8 {
    return std.fmt.allocPrint(allocator, "{s}/{s}.events.jsonl", .{ serve_dir, name });
}

/// A session name is both a URL path segment and a file name, so it is
/// restricted to characters that are unambiguous in both and can never walk
/// out of `.graff/`.
pub fn validName(name: []const u8) bool {
    if (name.len == 0 or name.len > 64) return false;
    if (name[0] == '.' or name[0] == '-') return false;
    for (name) |c| {
        const ok = (c >= 'a' and c <= 'z') or (c >= 'A' and c <= 'Z') or
            (c >= '0' and c <= '9') or c == '-' or c == '_' or c == '.';
        if (!ok) return false;
    }
    return true;
}

/// Append-only writer for one live session. Best-effort throughout: losing the
/// log degrades resumability, it must never fail a turn. On any write error the
/// file is dropped rather than kept at a drifted offset (#242's lesson: a
/// swallowed short write silently corrupts every later record).
pub const EventLog = struct {
    io: Io,
    file: ?Io.File = null,
    offset: u64 = 0,

    pub fn open(io: Io, dir: Io.Dir, path: []const u8) EventLog {
        if (std.fs.path.dirname(path)) |parent| dir.createDirPath(io, parent) catch {};
        const file = dir.createFile(io, path, .{ .truncate = false }) catch return .{ .io = io };
        const size: u64 = if (file.stat(io)) |st| st.size else |_| 0;
        return .{ .io = io, .file = file, .offset = size };
    }

    pub fn close(self: *EventLog) void {
        if (self.file) |f| f.close(self.io);
        self.file = null;
    }

    /// Persist one event line (without its newline; this adds it).
    pub fn append(self: *EventLog, line: []const u8) void {
        const file = self.file orelse return;
        file.writePositionalAll(self.io, line, self.offset) catch return self.close();
        self.offset += line.len;
        file.writePositionalAll(self.io, "\n", self.offset) catch return self.close();
        self.offset += 1;
    }
};

/// Highest `seq` persisted in `data`. 0 when the log is empty or unstamped.
/// Only COMPLETE (newline-terminated) lines count: a half-written tail is a
/// mid-append artifact, and reporting its id as the end of the tape would tell
/// a reconnecting client to skip past an event it never received.
pub fn lastSeqOf(data: []const u8) u64 {
    var high: u64 = 0;
    var rest = data;
    while (std.mem.indexOfScalar(u8, rest, '\n')) |nl| {
        const line = std.mem.trim(u8, rest[0..nl], " \t\r");
        rest = rest[nl + 1 ..];
        if (line.len == 0) continue;
        if (protocol_seq.seqOf(line)) |s| high = @max(high, s);
    }
    return high;
}

/// Highest `seq` already on disk for `name`, so a fresh bridge can tell a
/// client where the tape ends before it reconnects.
pub fn lastSeqOnDisk(io: Io, dir: Io.Dir, gpa: Allocator, path: []const u8) u64 {
    const data = dir.readFileAlloc(io, path, gpa, .limited(max_log_bytes)) catch return 0;
    defer gpa.free(data);
    return lastSeqOf(data);
}

pub const Replayed = struct {
    /// Lines written to the sink.
    emitted: usize = 0,
    /// Highest seq written; 0 when nothing matched.
    last_seq: u64 = 0,
    /// The last line written terminates a protocol request.
    terminal: bool = false,
};

/// Write every COMPLETE line of `data` whose stamped seq is >= `from`.
///
/// A trailing partial line (the producer is mid-append) is deliberately not
/// written — the caller polls again once its newline lands, which is what makes
/// duplicate-free tailing possible. Unstamped lines are skipped rather than
/// guessed at, so replay can never invent a position. CRLF tolerant.
pub fn replay(w: *Io.Writer, data: []const u8, from: u64) !Replayed {
    var out: Replayed = .{};
    var rest = data;
    while (std.mem.indexOfScalar(u8, rest, '\n')) |nl| {
        const raw = rest[0..nl];
        rest = rest[nl + 1 ..];
        const line = std.mem.trim(u8, raw, " \t\r");
        if (line.len == 0) continue;
        const seq = protocol_seq.seqOf(line) orelse continue;
        if (seq < from) continue;
        try w.writeAll(line);
        try w.writeByte('\n');
        out.emitted += 1;
        out.last_seq = seq;
        out.terminal = terminalEvent(line);
    }
    return out;
}

/// Streams complete lines appended to a log by ANOTHER writer (the in-flight
/// request, possibly in this process, possibly not). Stateless about partial
/// lines: the file offset only ever advances past a newline, so a line that is
/// still being written is simply re-read on the next poll.
pub const Follower = struct {
    io: Io,
    file: ?Io.File = null,
    offset: u64 = 0,
    buf: []u8,

    pub fn open(io: Io, dir: Io.Dir, path: []const u8, buf: []u8, from_offset: u64) Follower {
        const file = dir.openFile(io, path, .{}) catch return .{ .io = io, .buf = buf };
        return .{ .io = io, .file = file, .buf = buf, .offset = from_offset };
    }

    pub fn close(self: *Follower) void {
        if (self.file) |f| f.close(self.io);
        self.file = null;
    }

    /// Bytes ending at the last complete line, or "" when nothing new landed.
    pub fn poll(self: *Follower) []const u8 {
        const file = self.file orelse return "";
        const size = (file.stat(self.io) catch return "").size;
        if (size <= self.offset) return "";
        const want: usize = @intCast(@min(@as(u64, self.buf.len), size - self.offset));
        const got = file.readPositionalAll(self.io, self.buf[0..want], self.offset) catch return "";
        const chunk = self.buf[0..got];
        const last_nl = std.mem.lastIndexOfScalar(u8, chunk, '\n') orelse return "";
        self.offset += last_nl + 1;
        return chunk[0 .. last_nl + 1];
    }
};

/// Every event type that ends a protocol request: turn/error close user turns,
/// the rest are the between-turn acks mainloop.zig emits for control requests.
/// An ack missing from this list wedges the session PERMANENTLY — serve.zig
/// streams it and then blocks in takeDelimiter() still holding `busy`, so every
/// later request on that session waits on a lock nobody will release. The test
/// below pins this list against mainloop.zig's INLINE control block only, so a
/// handler that emits its ack from its own module (mainloop_score.zig does)
/// stays invisible to the scan and needs its own case there.
pub const terminal_events = [_][]const u8{
    "turn",
    "error",
    "system_prompt",
    "score",
    "model",
    "compact",
    "mode",
    "agent",
    "effort",
    "fast",
    "ultracode",
};

/// Is this child event line the terminal event of a protocol request? Unknown
/// event types stream through (edge-version durability) — a newer child must
/// still terminate every request with one of these.
pub fn terminalEvent(line: []const u8) bool {
    const t = stringField(line, "type") orelse "";
    for (terminal_events) |name| {
        if (std.mem.eql(u8, t, name)) return true;
    }
    return false;
}

/// Pull a JSON string field out of an event line by scanning, not parsing:
/// `type` sits in the envelope, so this stays O(1) on a MiB-sized tool_result.
pub fn stringField(line: []const u8, field: []const u8) ?[]const u8 {
    var needle_buf: [64]u8 = undefined;
    if (field.len + 4 > needle_buf.len) return null;
    const needle = std.fmt.bufPrint(&needle_buf, "\"{s}\":\"", .{field}) catch return null;
    const start = std.mem.indexOf(u8, line, needle) orelse return null;
    var i = start + needle.len;
    while (i < line.len) : (i += 1) {
        if (line[i] == '\\') {
            i += 1;
            continue;
        }
        if (line[i] == '"') return line[start + needle.len .. i];
    }
    return null;
}

/// `from` out of a request target's query string (`/v1/…?from=12&x=y`).
pub fn queryU64(query: []const u8, key: []const u8) ?u64 {
    var it = std.mem.splitAny(u8, query, "&;");
    while (it.next()) |pair| {
        const eq = std.mem.indexOfScalar(u8, pair, '=') orelse continue;
        if (!std.mem.eql(u8, pair[0..eq], key)) continue;
        return std.fmt.parseInt(u64, pair[eq + 1 ..], 10) catch null;
    }
    return null;
}

/// Split a request target into path and query. No query -> "".
pub fn splitTarget(target: []const u8) struct { path: []const u8, query: []const u8 } {
    const q = std.mem.indexOfScalar(u8, target, '?') orelse return .{ .path = target, .query = "" };
    return .{ .path = target[0..q], .query = target[q + 1 ..] };
}

const testing = std.testing;

test "replay: from=N is inclusive, gap-free, and never duplicates" {
    const log =
        "{\"seq\":1,\"type\":\"started\"}\n" ++
        "{\"seq\":2,\"type\":\"text\",\"text\":\"a\"}\n" ++
        "{\"seq\":3,\"type\":\"text\",\"text\":\"b\"}\n" ++
        "{\"seq\":4,\"type\":\"turn\",\"text\":\"done\"}\n";
    var buf: [1024]u8 = undefined;
    var w: Io.Writer = .fixed(&buf);
    const all = try replay(&w, log, 1);
    try testing.expectEqual(@as(usize, 4), all.emitted);
    try testing.expectEqual(@as(u64, 4), all.last_seq);
    try testing.expect(all.terminal); // the turn event closes the request
    try testing.expectEqualStrings(log, w.buffered());

    var buf2: [1024]u8 = undefined;
    var w2: Io.Writer = .fixed(&buf2);
    const tail = try replay(&w2, log, 3);
    try testing.expectEqual(@as(usize, 2), tail.emitted);
    try testing.expect(std.mem.startsWith(u8, w2.buffered(), "{\"seq\":3,"));
    try testing.expect(std.mem.indexOf(u8, w2.buffered(), "\"seq\":2") == null);

    // Past the end: nothing replayed, and nothing invented.
    var buf3: [64]u8 = undefined;
    var w3: Io.Writer = .fixed(&buf3);
    const none = try replay(&w3, log, 99);
    try testing.expectEqual(@as(usize, 0), none.emitted);
    try testing.expectEqual(@as(u64, 0), none.last_seq);
    try testing.expect(!none.terminal);
    try testing.expectEqual(@as(usize, 0), w3.buffered().len);
}

test "replay: holds back a partial line, tolerates CRLF and unstamped noise" {
    // The producer is mid-append: the last line has no newline yet.
    const log = "{\"seq\":1,\"type\":\"text\"}\r\n\r\n{\"type\":\"error\"}\n{\"seq\":2,\"type\":\"tur";
    var buf: [512]u8 = undefined;
    var w: Io.Writer = .fixed(&buf);
    const got = try replay(&w, log, 1);
    try testing.expectEqual(@as(usize, 1), got.emitted); // seq 2 is still partial
    try testing.expectEqual(@as(u64, 1), got.last_seq);
    // CR stripped, blank line skipped, unstamped line skipped rather than guessed.
    try testing.expectEqualStrings("{\"seq\":1,\"type\":\"text\"}\n", w.buffered());
    try testing.expectEqual(@as(u64, 1), lastSeqOf(log));
}

test "lastSeqOf reads the high-water mark of a log" {
    try testing.expectEqual(@as(u64, 0), lastSeqOf(""));
    try testing.expectEqual(@as(u64, 0), lastSeqOf("{\"type\":\"text\"}\n"));
    try testing.expectEqual(@as(u64, 7), lastSeqOf("{\"seq\":5,\"type\":\"a\"}\n{\"seq\":7,\"type\":\"b\"}\n"));
}

test "validName keeps a session name inside .graff and inside one URL segment" {
    try testing.expect(validName("a1b2c3d4e5f60718"));
    try testing.expect(validName("nightly_run-2"));
    try testing.expect(!validName(""));
    try testing.expect(!validName("../../etc/passwd"));
    try testing.expect(!validName(".hidden"));
    try testing.expect(!validName("has space"));
    try testing.expect(!validName("slash/inside"));
    var long: [65]u8 = undefined;
    @memset(&long, 'a');
    try testing.expect(!validName(&long));
}

test "queryU64 + splitTarget: ?from=N off a request target" {
    const split = splitTarget("/v1/sessions/abc/events?from=12&x=y");
    try testing.expectEqualStrings("/v1/sessions/abc/events", split.path);
    try testing.expectEqual(@as(u64, 12), queryU64(split.query, "from").?);
    try testing.expect(queryU64(split.query, "missing") == null);
    const bare = splitTarget("/healthz");
    try testing.expectEqualStrings("/healthz", bare.path);
    try testing.expectEqualStrings("", bare.query);
    try testing.expect(queryU64(bare.query, "from") == null);
    try testing.expect(queryU64("from=notanumber", "from") == null);
}

test "terminalEvent + stringField: envelope reads survive a seq prefix" {
    try testing.expect(terminalEvent("{\"seq\":9,\"type\":\"turn\",\"text\":\"x\"}"));
    try testing.expect(terminalEvent("{\"seq\":9,\"type\":\"error\",\"message\":\"x\"}"));
    try testing.expect(!terminalEvent("{\"seq\":9,\"type\":\"text\",\"text\":\"x\"}"));
    try testing.expect(!terminalEvent("{\"seq\":9,\"type\":\"tool_call\",\"name\":\"bash\"}"));
    // set_ultracode's ack: absent from this list it streams and then blocks,
    // holding `busy` for the life of the session.
    try testing.expect(terminalEvent("{\"seq\":9,\"type\":\"ultracode\",\"ok\":true,\"on\":true}"));
    try testing.expectEqualStrings("turn", stringField("{\"seq\":1,\"type\":\"turn\"}", "type").?);
    try testing.expect(stringField("{\"seq\":1,\"type\":\"turn\"}", "missing") == null);
    // escaped quote inside the value is skipped, not treated as the terminator
    try testing.expectEqualStrings("a\\\"b", stringField("{\"text\":\"a\\\"b\"}", "text").?);
}

test "EventLog + Follower: appended lines tail without gaps or duplicates" {
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    // Exactly the path serve builds, including the .graff/serve/ chain the
    // writer has to create for itself on a cold workspace.
    const path = try logPath(testing.allocator, "run-1");
    defer testing.allocator.free(path);

    var log = EventLog.open(io, tmp.dir, path);
    defer log.close();
    log.append("{\"seq\":1,\"type\":\"started\"}");
    log.append("{\"seq\":2,\"type\":\"text\",\"text\":\"a\"}");

    var buf: [4096]u8 = undefined;
    var follower = Follower.open(io, tmp.dir, path, &buf, 0);
    defer follower.close();
    var out: [4096]u8 = undefined;
    var w: Io.Writer = .fixed(&out);
    const first = try replay(&w, follower.poll(), 1);
    try testing.expectEqual(@as(usize, 2), first.emitted);
    try testing.expect(!first.terminal);

    // Nothing new: the follower yields nothing rather than replaying itself.
    try testing.expectEqualStrings("", follower.poll());

    log.append("{\"seq\":3,\"type\":\"turn\",\"text\":\"done\"}");
    var out2: [4096]u8 = undefined;
    var w2: Io.Writer = .fixed(&out2);
    const second = try replay(&w2, follower.poll(), 1);
    try testing.expectEqual(@as(usize, 1), second.emitted);
    try testing.expectEqual(@as(u64, 3), second.last_seq);
    try testing.expect(second.terminal);

    // A second process re-opening the same log appends past the tape, and the
    // on-disk high-water mark is what a fresh bridge reports to its client.
    var reopened = EventLog.open(io, tmp.dir, path);
    defer reopened.close();
    try testing.expectEqual(@as(u64, 3), lastSeqOnDisk(io, tmp.dir, testing.allocator, path));
    reopened.append("{\"seq\":4,\"type\":\"started\"}");
    try testing.expectEqual(@as(u64, 4), lastSeqOnDisk(io, tmp.dir, testing.allocator, path));
}

test "terminal_events covers every control ack mainloop can emit" {
    // The list is only correct relative to the emitter, so read the emitter.
    // mainloop.zig's --json control block answers each between-turn request
    // with exactly one event; any type of those that is not terminal wedges
    // the session in serveMessage. Pinned as source text (route_policy_tests
    // does the same for subagent.zig) because the property is about the emit
    // sites, not about a value a runtime test could observe here.
    const src = @embedFile("mainloop.zig");
    const begin = std.mem.indexOf(u8, src, "json_request = std.json.parseFromSlice") orelse
        return error.ControlBlockMoved;
    const end = begin + (std.mem.indexOf(u8, src[begin..], "break :blk text;") orelse
        return error.ControlBlockMoved);
    const block = src[begin..end];

    // Every ack in the block is a one-liner, which is what the scan below
    // reads; a wrapped `.emit(.{` would slip past it entirely unchecked.
    const emit = ".emit(.{";
    const typed_emit = emit ++ " .type = \"";
    const typed = std.mem.count(u8, block, typed_emit);
    try testing.expectEqual(std.mem.count(u8, block, emit), typed);

    var checked: usize = 0;
    var rest = block;
    while (std.mem.indexOf(u8, rest, typed_emit)) |at| {
        const from = at + typed_emit.len;
        const stop = from + (std.mem.indexOfScalar(u8, rest[from..], '"') orelse return error.ControlBlockMoved);
        const name = rest[from..stop];
        rest = rest[stop..];
        var buf: [512]u8 = undefined;
        const line = std.fmt.bufPrint(&buf, "{{\"seq\":1,\"type\":\"{s}\"}}", .{name}) catch {
            std.debug.print("\nack name of {d} bytes starting \"{s}\" overflows this test's scratch buffer — enlarge buf\n", .{ name.len, name[0..@min(name.len, 48)] });
            return error.ControlAckNameTooLong;
        };
        if (!terminalEvent(line)) {
            std.debug.print("\ncontrol ack \"{s}\" is missing from serve_events.terminal_events\n", .{name});
            return error.ControlAckNotTerminal;
        }
        checked += 1;
    }
    // Exact, so a scan that skips an emit (rather than finding a bad one) still
    // fails; plus a floor, because the markers above could match a shorter
    // region and leave both counts trivially in agreement. 17 acks today, and
    // this only trips if acks are DELETED — adding one is fine.
    try testing.expectEqual(typed, checked);
    try testing.expect(checked >= 17);

    // score is acked from its own module; answer/reattach never reach the
    // streaming loop (serve.zig answers both before serveMessage sends).
    const score_src = @embedFile("mainloop_score.zig");
    try testing.expect(std.mem.indexOf(u8, score_src, ".emit(.{ .type = \"score\"") != null);
    try testing.expect(terminalEvent("{\"seq\":1,\"type\":\"score\"}"));
}