Skip to content

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

Python
16.9 KB
Raw Blame
//! Durable peer-channel state on the session file (ADR 0014).
//!
//! Codex keeps a thread cursor and reuses `prompt_cache_key` across compact
//! and resume. OpenCode pages session parts from a cursor and does not replay
//! side-channel chatter into the next request. Claude Code's SendMessage inbox
//! lives on disk so resume can pull. Graff's room offsets and parked inbox
//! used to be process-local: `/resume` re-drained the last 10 JSONL lines,
//! re-injected a `[peer]` wake, and titled the session after the firehose.
//!
//! The session file now carries the byte cursors and the parked bodies.
//! History on disk drops the perishable wakes (ADR 0004). Resume restores
//! the mailbox; it does not replay the room.

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

const agent_mod = @import("agent.zig");
const Agent = agent_mod.Agent;
const main_mod = @import("main.zig");
const peer_channel = @import("peer_channel.zig");
const peer_context = @import("peer_context.zig");
const peer_inbox = @import("peer_inbox.zig");
const presence = @import("presence.zig");
const session_writer = @import("session_writer.zig");

/// A human user turn — not a `[peer]` / `[presence]` inject. Title, meaningful-
/// state, and "first prompt" all use this so a wake cannot mint a session.
pub fn isHumanUserTurn(m: Value) bool {
    if (m != .object) return false;
    const role = m.object.get("role") orelse return false;
    if (role != .string or !std.mem.eql(u8, role.string, "user")) return false;
    return !@import("session_wake.zig").isNotice(m) and !peer_context.isPeerInject(m);
}

/// Messages written to `.session.json`: wakes stay out. The transcript still
/// recorded them when they first entered history; compact / resume must not
/// keep paying for them on every later request.
pub fn messagesForSave(arena: Allocator, items: []const Value) !std.json.Array {
    var out = std.json.Array.init(arena);
    for (items) |m| {
        if (peer_context.isPeerInject(m)) continue;
        try out.append(m);
    }
    return out;
}

/// Drop wakes the model has not been sent yet: those after the last
/// non-user message. A wake earlier in history was already sent and
/// answered; removing it rewrote history the provider had cached (and made
/// Claude Agent start a fresh process) on every step after an inbox read.
pub fn dropUnsentInjects(msgs: *std.json.Array) void {
    var start = msgs.items.len;
    while (start > 0) : (start -= 1) {
        const m = msgs.items[start - 1];
        if (m != .object) break;
        const role = m.object.get("role") orelse break;
        if (role != .string or !std.mem.eql(u8, role.string, "user")) break;
    }
    var i = start;
    while (i < msgs.items.len) {
        if (peer_context.isPeerInject(msgs.items[i])) {
            _ = msgs.orderedRemove(i);
            continue;
        }
        i += 1;
    }
}

pub fn dropAllInjects(msgs: *std.json.Array) void {
    var i: usize = 0;
    while (i < msgs.items.len) {
        if (peer_context.isPeerInject(msgs.items[i])) {
            _ = msgs.orderedRemove(i);
            continue;
        }
        i += 1;
    }
}

pub fn mixFingerprint(f: *session_writer.Fingerprint) void {
    const cur = presence.roomCursor();
    f.num(cur.chan);
    f.num(cur.device);
    peer_inbox.mixFingerprint(f);
}

pub fn writeFields(s: *std.json.Stringify) !void {
    const cur = presence.roomCursor();
    try s.objectField("chan_off");
    try s.write(cur.chan);
    try s.objectField("device_off");
    try s.write(cur.device);
    try s.objectField("peer_inbox");
    try peer_inbox.writeJson(s);
    try s.objectField("peer_inbox_dropped");
    try s.write(peer_inbox.dropped());
}

fn u64Field(obj: std.json.ObjectMap, name: []const u8) ?u64 {
    const v = obj.get(name) orelse return null;
    if (v != .integer or v.integer < 0) return null;
    return @intCast(v.integer);
}

fn injectWake(root: *Agent) void {
    var obj: std.json.ObjectMap = .empty;
    obj.put(root.arena, "role", .{ .string = "user" }) catch return;
    obj.put(root.arena, "content", .{ .string = peer_context.capInject(peer_inbox.formatWake(root.arena)) }) catch return;
    root.messages.append(.{ .object = obj }) catch {};
}

/// After messages are restored: drop leftover wakes, adopt the room cursor
/// (or seek to tail on a legacy file / `-p` one-shot), restore the mailbox,
/// and inject at most one wake when something is still unread.
pub fn restore(root: *Agent, obj: std.json.ObjectMap) void {
    dropAllInjects(&root.messages);
    // One-shots must not hear predating chatter (ADR 0004 measured ~4k tokens
    // of stale room on the first step). Inbox restore would re-surface it.
    if (main_mod.unattended) {
        presence.seekRoomsToTail(root.io, root.arena);
        peer_inbox.clear();
        return;
    }
    if (obj.get("chan_off") != null or obj.get("device_off") != null) {
        presence.adoptRoomCursor(.{
            .chan = u64Field(obj, "chan_off") orelse 0,
            .device = u64Field(obj, "device_off") orelse 0,
        });
        // Catch-up after downtime is live traffic, not a first-join backlog.
        // Without this, deliverInbound would drop everything past the last 10.
        peer_channel.markCaughtUp();
    } else {
        // Pre-0014 file: no cursor. Seek rather than replay the last 10 lines.
        presence.seekRoomsToTail(root.io, root.arena);
    }
    // restoreJson clears both bodies and loss accounting, even for a legacy
    // session with no mailbox. Add the saved count AFTER array evictions.
    peer_inbox.restoreJson(obj.get("peer_inbox") orelse .null);
    if (obj.get("peer_inbox_dropped")) |v| peer_inbox.restoreDropped(v);
    if (peer_inbox.pending()) injectWake(root);
}

const testing = std.testing;

fn userText(arena: Allocator, s: []const u8) !Value {
    const raw = try std.fmt.allocPrint(arena, "{{\"role\":\"user\",\"content\":\"{s}\"}}", .{s});
    return std.json.parseFromSliceLeaky(Value, arena, raw, .{});
}

fn asstText(arena: Allocator, s: []const u8) !Value {
    const raw = try std.fmt.allocPrint(arena, "{{\"role\":\"assistant\",\"content\":\"{s}\"}}", .{s});
    return std.json.parseFromSliceLeaky(Value, arena, raw, .{});
}

test "isHumanUserTurn: peer wakes are not a human prompt" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    try testing.expect(isHumanUserTurn(try userText(a, "keep going")));
    try testing.expect(!isHumanUserTurn(try userText(a, "[peer] 1 unread from s-2 — peer_message action=inbox")));
    try testing.expect(!isHumanUserTurn(try userText(a, "[peer message from a]: hold off")));
    try testing.expect(!isHumanUserTurn(try asstText(a, "keep going")));
}

test "messagesForSave / dropAllInjects: wakes leave the durable history" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    var live = std.json.Array.init(a);
    try live.append(try userText(a, "fix the parser"));
    try live.append(try userText(a, "[peer] 2 unread from s-a — peer_message action=inbox"));
    try live.append(try asstText(a, "on it"));
    try live.append(try userText(a, "[presence] 1 other live session"));
    const saved = try messagesForSave(a, live.items);
    try testing.expectEqual(@as(usize, 2), saved.items.len);
    try testing.expectEqualStrings("fix the parser", saved.items[0].object.get("content").?.string);
    try testing.expectEqualStrings("on it", saved.items[1].object.get("content").?.string);
    dropAllInjects(&live);
    try testing.expectEqual(@as(usize, 2), live.items.len);
}

test "writeFields / restoreJson: inbox bodies survive a process restart" {
    peer_inbox.clear();
    defer peer_inbox.clear();
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    const presence_chan = @import("presence_chan.zig");
    const local = [_]presence_chan.Message{.{ .from_session = "s-a", .text = "hold gui/src", .to = "" }};
    const device = [_]presence_chan.Message{.{ .from_session = "s-b", .text = "your turn", .to = "me" }};
    try testing.expectEqual(@as(usize, 2), peer_inbox.parkHeard(&local, &device));

    var aw: std.Io.Writer.Allocating = .init(a);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try s.beginObject();
    try writeFields(&s);
    try s.endObject();
    const parsed = try std.json.parseFromSliceLeaky(Value, a, aw.writer.buffered(), .{});
    try testing.expect(parsed.object.get("chan_off") != null);
    try testing.expect(parsed.object.get("device_off") != null);

    peer_inbox.clear();
    try testing.expectEqual(@as(usize, 0), peer_inbox.unread());
    peer_inbox.restoreJson(parsed.object.get("peer_inbox").?);
    try testing.expectEqual(@as(usize, 2), peer_inbox.unread());
    const body = try peer_inbox.takeAll(a);
    try testing.expect(std.mem.indexOf(u8, body, "hold gui/src") != null);
    try testing.expect(std.mem.indexOf(u8, body, "your turn") != null);
}

test "inbox resume and tool dispatch retain full bodies and overflow notice" {
    peer_inbox.clear();
    defer peer_inbox.clear();
    const unattended = main_mod.unattended;
    main_mod.unattended = false;
    defer main_mod.unattended = unattended;
    var arena = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const prefix = try a.alloc(u8, 220);
    @memset(prefix, 'x');
    const text = try std.fmt.allocPrint(a, "{s} — wait for my handoff", .{prefix});
    for (0..peer_inbox.inbox_cap + 2) |_| {
        _ = peer_inbox.parkHeard(&.{.{ .from_session = "sender", .text = text }}, &.{});
    }
    var aw: std.Io.Writer.Allocating = .init(a);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try s.beginObject();
    try writeFields(&s);
    try s.endObject();
    const saved = try std.json.parseFromSliceLeaky(Value, a, aw.writer.buffered(), .{});
    peer_inbox.clear();
    var root: Agent = undefined;
    root.arena = a;
    root.io = testing.io;
    root.messages = std.json.Array.init(a);
    restore(&root, saved.object);
    try testing.expectEqual(@as(usize, 2), peer_inbox.dropped());
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
    try testing.expect(std.mem.indexOf(u8, root.messages.items[0].object.get("content").?.string, "2 dropped") != null);
    const call = @import("tools.zig").ToolCall{
        .id = "inbox",
        .name = "peer_message",
        .input = try std.json.parseFromSliceLeaky(Value, a, "{\"action\":\"inbox\"}", .{}),
    };
    const result = try peer_channel.handleMessage(&root, call);
    try testing.expect(!result.is_error);
    try testing.expect(std.mem.indexOf(u8, result.text, text) != null);
    try testing.expect(std.mem.indexOf(u8, result.text, "2 dropped message(s)") != null);
    try testing.expectEqual(@as(usize, 0), peer_inbox.dropped());
    try testing.expectEqual(@as(usize, 0), peer_inbox.unread());
}

test "legacy session without cursor fields seeks rather than replaying (restore path)" {
    // restore() with no chan_off seeks; seek is a no-op without a registry.
    // What we can prove here: leftover wakes are stripped and an empty inbox
    // does not mint a new wake.
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    peer_inbox.clear();
    defer peer_inbox.clear();
    presence.resetRoomCursorForTest();
    defer presence.resetRoomCursorForTest();
    var root: Agent = undefined;
    root.arena = a;
    root.io = testing.io;
    root.messages = std.json.Array.init(a);
    try root.messages.append(try userText(a, "real prompt"));
    try root.messages.append(try userText(a, "[peer] 3 unread from old — peer_message action=inbox"));
    const empty = try std.json.parseFromSliceLeaky(Value, a, "{}", .{});
    restore(&root, empty.object);
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
    try testing.expect(isHumanUserTurn(root.messages.items[0]));
}

fn restoreTestRoot(a: Allocator) Agent {
    var root: Agent = undefined;
    root.arena = a;
    root.io = testing.io;
    root.messages = std.json.Array.init(a);
    return root;
}

test "session peer restore dispatch: full body roundtrip, legacy reset, loss-only wake and one-shot" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    peer_inbox.clear();
    defer peer_inbox.clear();
    presence.resetRoomCursorForTest();
    defer presence.resetRoomCursorForTest();
    const unattended = main_mod.unattended;
    main_mod.unattended = false;
    defer main_mod.unattended = unattended;
    const text = &@import("util.zig").repeatBytes("long body beyond the old clipping boundary: ", 20);
    const sender = &@import("util.zig").repeatBytes("sender-beyond-the-old-fixed-buffer-", 3);
    const Message = @import("presence_chan.zig").Message;
    for (0..peer_inbox.inbox_cap + 2) |_| {
        _ = peer_inbox.parkHeard(&.{Message{ .from_session = sender, .text = text, .to = "me" }}, &.{});
    }
    var aw: std.Io.Writer.Allocating = .init(a);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try s.beginObject();
    try writeFields(&s);
    try s.endObject();
    const parsed = try std.json.parseFromSliceLeaky(Value, a, aw.writer.buffered(), .{});
    try testing.expectEqual(@as(i64, 2), parsed.object.get("peer_inbox_dropped").?.integer);
    const saved = parsed.object.get("peer_inbox").?.array.items;
    try testing.expectEqualStrings(text, saved[0].object.get("text").?.string);
    try testing.expectEqualStrings(sender, saved[0].object.get("from").?.string);
    peer_inbox.clear();
    var root = restoreTestRoot(a);
    restore(&root, parsed.object);
    try testing.expectEqual(peer_inbox.inbox_cap, peer_inbox.unread());
    try testing.expectEqual(@as(usize, 2), peer_inbox.dropped());
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
    const body = try peer_inbox.takeAll(a);
    try testing.expect(std.mem.indexOf(u8, body, text) != null);
    try testing.expect(std.mem.indexOf(u8, body, sender) != null);

    // A legacy array resets previously accumulated loss accounting.
    const legacy = try std.json.parseFromSliceLeaky(Value, a, "{\"chan_off\":0,\"peer_inbox\":[{\"from\":\"old\",\"text\":\"legacy body\"}]}", .{});
    peer_inbox.restoreDropped(.{ .integer = 9 });
    restore(&root, legacy.object);
    try testing.expectEqual(@as(usize, 1), peer_inbox.unread());
    try testing.expectEqual(@as(usize, 0), peer_inbox.dropped());
    peer_inbox.restoreDropped(.{ .integer = 9 });
    const empty = try std.json.parseFromSliceLeaky(Value, a, "{}", .{});
    restore(&root, empty.object);
    try testing.expect(!peer_inbox.pending());
    try testing.expectEqual(@as(usize, 0), root.messages.items.len);

    const loss = try std.json.parseFromSliceLeaky(Value, a, "{\"chan_off\":0,\"peer_inbox_dropped\":3}", .{});
    var before = session_writer.Fingerprint.init();
    mixFingerprint(&before);
    restore(&root, loss.object);
    try testing.expectEqual(@as(usize, 0), peer_inbox.unread());
    try testing.expectEqual(@as(usize, 3), peer_inbox.dropped());
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
    try testing.expect(!isHumanUserTurn(root.messages.items[0]));
    var after = session_writer.Fingerprint.init();
    mixFingerprint(&after);
    try testing.expect(before.h.final() != after.h.final());
    restore(&root, loss.object);
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
    try testing.expectEqual(@as(usize, 3), peer_inbox.dropped());
    main_mod.unattended = true;
    restore(&root, parsed.object);
    try testing.expect(!peer_inbox.pending());
    try testing.expectEqual(@as(usize, 0), root.messages.items.len);
}

test "session peer restore dispatch: saved loss adds to oversized array evictions" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    peer_inbox.clear();
    defer peer_inbox.clear();
    presence.resetRoomCursorForTest();
    defer presence.resetRoomCursorForTest();
    const unattended = main_mod.unattended;
    main_mod.unattended = false;
    defer main_mod.unattended = unattended;
    var parsed = try std.json.parseFromSliceLeaky(Value, a, "{\"chan_off\":0,\"peer_inbox\":[],\"peer_inbox_dropped\":5}", .{});
    const item = try std.json.parseFromSliceLeaky(Value, a, "{\"from\":\"peer\",\"text\":\"body\"}", .{});
    const items = parsed.object.getPtr("peer_inbox").?;
    for (0..peer_inbox.inbox_cap + 2) |_| try items.array.append(item);
    var root = restoreTestRoot(a);
    restore(&root, parsed.object);
    try testing.expectEqual(peer_inbox.inbox_cap, peer_inbox.unread());
    try testing.expectEqual(@as(usize, 7), peer_inbox.dropped());
    try testing.expectEqual(@as(usize, 1), root.messages.items.len);
}