Skip to content

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

Python
19.2 KB
Raw Blame
//! Process-local parked inbound for `peer_message` (Claude-style pull).
//!
//! The JSONL room is the log. `deliverInbound` does not copy bodies into
//! history — it parks a small ring here and injects a one-line `[peer]` wake.
//! `action=inbox` reads+clears; `action=list` is who is live. Bodies never
//! ride every later request unless the model asked. A standing liaison is
//! still the wrong shape (ADR 0004): this is a mailbox, not another model.

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

const peer_context = @import("peer_context.zig");
const presence_chan = @import("presence_chan.zig");
const worktree_lease = @import("worktree_lease.zig");

const Message = presence_chan.Message;
const Owner = worktree_lease.Owner;

/// How many inbound bodies the process will hold. Evictions are counted;
/// the room still has the original messages on disk.
pub const inbox_cap: usize = 8;

// Owned independently of the delivery arena, which resets between steps.
var test_storage: Allocator = std.heap.page_allocator;
const storage = if (@import("builtin").is_test) &test_storage else &std.heap.page_allocator;

/// Clear with the previous allocator before changing ownership domains.
pub fn setStorageAllocatorForTest(allocator: Allocator) void {
    if (!@import("builtin").is_test) @compileError("test-only inbox allocator override");
    clear();
    test_storage = allocator;
}
const Parked = struct {
    from: []const u8,
    text: []const u8,
    dm: bool = false,
    device: bool = false,

    fn deinit(self: Parked) void {
        storage.free(self.from);
        storage.free(self.text);
    }
};

var g_items: [inbox_cap]Parked = undefined;
var g_head: usize = 0;
var g_len: usize = 0;
var g_dropped: usize = 0;
var g_gen: u64 = 0;

pub fn generation() u64 {
    return g_gen;
}

fn bumpGen() void {
    g_gen +%= 1;
}

pub fn clear() void {
    for (0..g_len) |i| itemAt(i).deinit();
    g_head = 0;
    g_len = 0;
    g_dropped = 0;
    bumpGen();
}

pub fn resetForTest() void {
    clear();
}

pub fn unread() usize {
    return g_len;
}

pub fn dropped() usize {
    return g_dropped;
}

pub fn pending() bool {
    return g_len > 0 or g_dropped > 0;
}

/// True when any parked body starts with `want` (daddy directives).
/// #1137: a sender marks a status or scope update that needs nothing from the
/// recipient. It stays readable but never starts a turn on its own.
pub const fyi_marker = "[fyi] ";

pub fn isFyi(text: []const u8) bool {
    return std.mem.startsWith(u8, std.mem.trimStart(u8, text, " \t\r\n"), std.mem.trimEnd(u8, fyi_marker, " "));
}

/// Whether any message parked at or after index `from` asks for a turn.
pub fn anyNeedsTurnFrom(from: usize) bool {
    var i = from;
    while (i < g_len) : (i += 1) {
        if (!isFyi(textSlice(itemAt(i)))) return true;
    }
    return false;
}

/// Whether any message parked at or after `from` was addressed to this
/// session (a DM, or the user's own `/tell` on the device room) and asks for
/// a turn. Unaddressed posts in this folder's room are ambient.
pub fn anyAddressedNeedsTurnFrom(from: usize) bool {
    var i = from;
    while (i < g_len) : (i += 1) {
        const p = itemAt(i);
        if ((p.dm or p.device) and !isFyi(textSlice(p))) return true;
    }
    return false;
}

pub fn anyTextPrefixed(want: []const u8) bool {
    var i: usize = 0;
    while (i < g_len) : (i += 1) {
        const text = textSlice(itemAt(i));
        const t = std.mem.trimStart(u8, text, " \t\r\n");
        if (std.mem.startsWith(u8, t, want)) return true;
    }
    return false;
}

/// Add saved loss after restoring the array, preserving any restore evictions.
pub fn restoreDropped(v: std.json.Value) void {
    const count = switch (v) {
        .integer => |n| if (n >= 0) (std.math.cast(usize, n) orelse std.math.maxInt(usize)) else return,
        // JSON stores unsigned counts above i64 as number strings.
        .number_string => |n| std.fmt.parseInt(usize, n, 10) catch return,
        else => return,
    };
    g_dropped +|= count;
}

fn parkOne(from: []const u8, text: []const u8, dm: bool, device: bool) void {
    const owned_from = storage.dupe(u8, from) catch {
        g_dropped +|= 1;
        return;
    };
    const owned_text = storage.dupe(u8, text) catch {
        storage.free(owned_from);
        g_dropped +|= 1;
        return;
    };
    // Allocate first: failure must not evict an otherwise readable message.
    if (g_len == inbox_cap) {
        itemAt(0).deinit();
        g_head = (g_head + 1) % inbox_cap;
        g_len -= 1;
        g_dropped +|= 1;
    }
    const i = (g_head + g_len) % inbox_cap;
    g_items[i] = .{ .from = owned_from, .text = owned_text, .dm = dm, .device = device };
    g_len += 1;
}

/// Copy heard room/device lines into the ring. Returns how many were heard
/// (including loss), so even an allocation failure prompts a loss-aware wake.
pub fn parkHeard(local: []const Message, device: []const Message) usize {
    var n: usize = 0;
    for (local) |m| {
        parkOne(m.from_session, m.text, m.to.len > 0, false);
        n += 1;
    }
    for (device) |m| {
        parkOne(m.from_session, m.text, m.to.len > 0, true);
        n += 1;
    }
    if (n > 0) bumpGen();
    return n;
}

fn itemAt(i: usize) *const Parked {
    return &g_items[(g_head + i) % inbox_cap];
}

fn fromSlice(p: *const Parked) []const u8 {
    return p.from;
}

fn textSlice(p: *const Parked) []const u8 {
    return p.text;
}

/// One-line history wake. Cheap on purpose: the bodies wait in the ring.
/// Advisory on purpose (#708): an imperative `peer_message action=inbox`
/// made a greeting's first step look like tool work.
pub fn formatWake(arena: Allocator) []const u8 {
    // Advisory framing (#708): the wake states that messages are waiting and
    // how to read them, but must not read as a command that displaces the
    // user's actual request on a trivial turn. Prefix stays "[peer]" — every
    // compact/peek path detects injects by prefix, not by this wording.
    if (!pending()) return "[peer] 0 unread — nothing waiting; no inbox read needed";
    if (g_dropped > 0) return std.fmt.allocPrint(arena, "[peer] {d} unread; {d} dropped — parked; peer_message action=inbox when relevant", .{ g_len, g_dropped }) catch "[peer] messages dropped — peer_message action=inbox when relevant";
    const first = fromSlice(itemAt(0));
    // Only the wake is a preview. Keep it one line and within the history cap.
    const line_end = std.mem.indexOfAny(u8, first, "\r\n") orelse first.len;
    var end = @min(line_end, 48);
    while (end > 0 and end < first.len and first[end] & 0xc0 == 0x80) end -= 1;
    const shown = first[0..end];
    var extra: usize = 0;
    for (1..@max(g_len, 1)) |i| {
        var seen = false;
        for (0..i) |j| {
            if (std.mem.eql(u8, fromSlice(itemAt(i)), fromSlice(itemAt(j)))) {
                seen = true;
                break;
            }
        }
        if (!seen) extra += 1;
    }
    const who = if (extra == 0)
        std.fmt.allocPrint(arena, "from {s}", .{shown}) catch "from a peer"
    else
        std.fmt.allocPrint(arena, "from {s} + {d} more", .{ shown, extra }) catch "from peers";
    return std.fmt.allocPrint(arena, "[peer] {d} unread {s} — parked; peer_message action=inbox when relevant", .{ g_len, who }) catch "[peer] unread — peer_message action=inbox when relevant";
}

/// #1137: replying is the exception. An unconditional "reply" here produced
/// acknowledgement turns and restated answers after informational mail.
pub const inbox_footer = "(inbox cleared — reply with peer_message only to a message that asks you something; [fyi] updates need no reply. Omit session for the room, or name one peer to DM)";

/// Read+clear only after the complete tool result is allocated successfully.
pub fn takeAll(arena: Allocator) Allocator.Error![]const u8 {
    if (!pending()) return "inbox empty";
    var buf: std.Io.Writer.Allocating = .init(arena);
    defer buf.deinit();
    if (g_dropped > 0) buf.writer.print("[peer inbox: {d} dropped message(s) could not be retained; the room log keeps the originals]\n", .{g_dropped}) catch return error.OutOfMemory;
    for (0..g_len) |i| {
        const p = itemAt(i);
        const flag = if (p.device and p.dm) " · device DM" else if (p.device) " · device" else if (p.dm) " · DM" else "";
        buf.writer.print("[peer message from {s}{s}]: {s}\n", .{ fromSlice(p), flag, textSlice(p) }) catch return error.OutOfMemory;
    }
    buf.writer.writeAll(inbox_footer) catch return error.OutOfMemory;
    const result = try buf.toOwnedSlice();
    clear();
    return result;
}

/// Digest parked bodies so a save skips only when the mailbox is unchanged.
pub fn mixFingerprint(f: anytype) void {
    f.num(g_len);
    f.num(g_dropped);
    var i: usize = 0;
    while (i < g_len) : (i += 1) {
        const p = itemAt(i);
        f.text(fromSlice(p));
        f.text(textSlice(p));
        f.flag(p.dm);
        f.flag(p.device);
    }
}

/// The parked ring as a JSON array for `.session.json`.
pub fn writeJson(s: *std.json.Stringify) !void {
    try s.beginArray();
    var i: usize = 0;
    while (i < g_len) : (i += 1) {
        const p = itemAt(i);
        try s.beginObject();
        try s.objectField("from");
        try s.write(fromSlice(p));
        try s.objectField("text");
        try s.write(textSlice(p));
        try s.objectField("dm");
        try s.write(p.dm);
        try s.objectField("device");
        try s.write(p.device);
        try s.endObject();
    }
    try s.endArray();
}

/// Replace the ring from a saved `peer_inbox` array. Garbage is skipped.
pub fn restoreJson(v: std.json.Value) void {
    clear();
    if (v != .array) return;
    for (v.array.items) |item| {
        if (item != .object) continue;
        const from = if (item.object.get("from")) |f| (if (f == .string) f.string else continue) else continue;
        const text = if (item.object.get("text")) |t| (if (t == .string) t.string else continue) else continue;
        const dm = if (item.object.get("dm")) |d| (d == .bool and d.bool) else false;
        const device = if (item.object.get("device")) |d| (d == .bool and d.bool) else false;
        parkOne(from, text, dm, device);
    }
}

/// Claude ListAgents: who is live, one short line each. Pull, not a push.
pub fn formatList(arena: Allocator, peers: []const Owner, mine: []const u8) []const u8 {
    if (peers.len == 0) return "no other live graff sessions";
    var buf: std.ArrayList(u8) = .empty;
    const head = std.fmt.allocPrint(arena, "{d} live:\n", .{peers.len}) catch "live:\n";
    buf.appendSlice(arena, head) catch {};
    for (peers) |p| {
        const where: []const u8 = if (std.mem.eql(u8, p.identity, mine)) "this-folder" else if (p.identity.len > 0) p.identity else "?";
        const goal = peer_context.clip(if (p.goal.len > 0) p.goal else "?", 40);
        const shown = if (p.title.len > 0) p.title else p.session_id;
        const base = if (p.session_base.len > 0) p.session_base else p.session_id;
        const line = std.fmt.allocPrint(arena, "{s} [{s}] {s} pid {d} {s} · {s}\n", .{ shown, base, p.session_id, p.pid, where, goal }) catch continue;
        buf.appendSlice(arena, line) catch {};
    }
    buf.appendSlice(arena, "DM with session=<title|base|id|pid|goal>; omit session for this folder's room. Presence is device-local.") catch {};
    return buf.items;
}

test "wake framing is advisory: it never opens with the read command (#708)" {
    resetForTest();
    defer resetForTest();
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    // Empty inbox: no imperative read of an empty mailbox.
    const idle = formatWake(a);
    try testing.expect(std.mem.startsWith(u8, idle, "[peer] 0 unread"));
    try testing.expect(std.mem.indexOf(u8, idle, "action=inbox") == null);
    // Parked: the how-to-read hint stays, but the wake must not BE the
    // command — the user's turn outranks the mailbox.
    _ = parkHeard(&.{msg("s-a", "ping", "")}, &.{});
    const wake = formatWake(a);
    try testing.expect(wake.len <= peer_context.inject_byte_cap);
    try testing.expect(std.mem.indexOf(u8, wake, "peer_message action=inbox when relevant") != null);
    try testing.expect(!std.mem.endsWith(u8, wake, "action=inbox"));
}

const testing = std.testing;

fn msg(from: []const u8, text: []const u8, to: []const u8) Message {
    return .{ .from_session = from, .text = text, .to = to };
}

fn peer(id: []const u8, pid: i32, goal: []const u8, identity: []const u8) Owner {
    return .{ .session_id = id, .pid = pid, .goal = goal, .identity = identity };
}

test "inbox ring: park, one-line wake, overflow drops oldest, takeAll clears" {
    // One test owns the process-local ring so parallel suite threads cannot
    // interleave park/take on the same slots (ADR 0004 mailbox is per-process).
    resetForTest();
    defer resetForTest();
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();

    const n = parkHeard(&.{msg("session-aaa", "hold gui/src", "")}, &.{msg("session-bbb", "your turn", "session-me")});
    try testing.expectEqual(@as(usize, 2), n);
    try testing.expectEqual(@as(usize, 2), unread());
    const wake = formatWake(a);
    try testing.expect(std.mem.startsWith(u8, wake, "[peer] 2 unread from session-aaa + 1 more"));
    try testing.expect(std.mem.indexOf(u8, wake, "peer_message action=inbox when relevant") != null);
    try testing.expect(std.mem.indexOf(u8, wake, "parked") != null);
    try testing.expect(std.mem.indexOf(u8, wake, "when relevant") != null);
    try testing.expect(std.mem.indexOfScalar(u8, wake, '\n') == null);
    const body = try takeAll(a);
    try testing.expect(std.mem.indexOf(u8, body, "[peer message from session-aaa]: hold gui/src") != null);
    try testing.expect(std.mem.indexOf(u8, body, "[peer message from session-bbb · device DM]: your turn") != null);
    try testing.expectEqual(@as(usize, 0), unread());
    try testing.expectEqualStrings("inbox empty", try takeAll(a));

    var i: usize = 0;
    while (i < inbox_cap + 2) : (i += 1) {
        const from = try std.fmt.allocPrint(a, "s-{d}", .{i});
        const text = try std.fmt.allocPrint(a, "line {d}", .{i});
        _ = parkHeard(&.{msg(from, text, "")}, &.{});
    }
    try testing.expectEqual(inbox_cap, unread());
    const overflow = try takeAll(a);
    try testing.expect(std.mem.indexOf(u8, overflow, "line 0") == null);
    try testing.expect(std.mem.indexOf(u8, overflow, "line 1") == null);
    try testing.expect(std.mem.indexOf(u8, overflow, try std.fmt.allocPrint(a, "line {d}", .{inbox_cap + 1})) != null);
}

test "inbox full UTF-8 bodies survive the channel, parking and JSON restore" {
    resetForTest();
    defer resetForTest();
    var arena = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    var tmp = testing.tmpDir(.{});
    defer tmp.cleanup();
    const prefix = try a.alloc(u8, 199);
    @memset(prefix, 'x');
    const text = try std.fmt.allocPrint(a, "{s}🟢\nDo not publish; wait for my handoff.\n", .{prefix});
    try testing.expect(presence_chan.postMessage(testing.io, a, tmp.dir, "room.jsonl", .{ .from_pid = 1, .from_session = "sender", .text = text }));
    var cursor: u64 = 0;
    _ = parkHeard(presence_chan.readNewMessages(testing.io, a, tmp.dir, "room.jsonl", &cursor), &.{});
    var aw: std.Io.Writer.Allocating = .init(a);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try writeJson(&s);
    const saved = try std.json.parseFromSliceLeaky(std.json.Value, a, aw.writer.buffered(), .{});
    restoreJson(saved);
    try testing.expect(std.mem.indexOf(u8, try takeAll(a), text) != null);
}

test "inbox wake counts distinct senders and a failed pull does not clear" {
    resetForTest();
    defer resetForTest();
    var arena = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    _ = parkHeard(&.{ msg("first", "one", ""), msg("second", "two", ""), msg("second", "three", "") }, &.{});
    const wake = formatWake(a);
    try testing.expect(std.mem.indexOf(u8, wake, "+ 1 more") != null);
    try testing.expect(wake.len <= peer_context.inject_byte_cap);
    var tiny: [1]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&tiny);
    try testing.expectError(error.OutOfMemory, takeAll(fba.allocator()));
    try testing.expectEqual(@as(usize, 3), unread());
    try testing.expect(std.mem.indexOf(u8, try takeAll(a), "three") != null);
}

test "formatList: one short line per peer; empty is honest" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    try testing.expectEqualStrings("no other live graff sessions", formatList(a, &.{}, "here"));
    const peers = [_]Owner{
        peer("session-aaa", 11, "rewrite the targeting", "here"),
        peer("session-bbb", 22, "paint chips", "/other/.git"),
    };
    const text = formatList(a, &peers, "here");
    try testing.expect(std.mem.startsWith(u8, text, "2 live:\n"));
    try testing.expect(std.mem.indexOf(u8, text, "session-aaa [session-aaa] session-aaa pid 11 this-folder · rewrite the targeting") != null);
    try testing.expect(std.mem.indexOf(u8, text, "session-bbb [session-bbb] session-bbb pid 22 /other/.git · paint chips") != null);
}

test "formatList: title and saved-session base lead the line" {
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    const peers = [_]Owner{.{
        .session_id = "session--aaa",
        .pid = 11,
        .goal = "recover login",
        .identity = "here",
        .title = "Fixing login recovery",
        .session_base = "fixing-login-recovery",
    }};
    const text = formatList(a, &peers, "here");
    try testing.expect(std.mem.indexOf(u8, text, "Fixing login recovery [fixing-login-recovery] session--aaa pid 11 this-folder · recover login") != null);
    try testing.expect(std.mem.indexOf(u8, text, "device-local") != null);
}

test "generation is stable for the same bodies and anyTextPrefixed sees [daddy]" {
    resetForTest();
    defer resetForTest();
    const empty = generation();
    try testing.expectEqual(empty, generation());
    _ = parkHeard(&.{msg("s-a", "[daddy] hold the tree", "")}, &.{});
    const once = generation();
    try testing.expect(once != empty);
    try testing.expectEqual(once, generation());
    try testing.expect(anyTextPrefixed("[daddy]"));
    try testing.expect(!anyTextPrefixed("[peer]"));
}

test "inbox JSON round-trip: restoreJson rebuilds the ring" {
    resetForTest();
    defer resetForTest();
    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena_state.deinit();
    const a = arena_state.allocator();
    _ = parkHeard(&.{msg("s-a", "hold the tree", "")}, &.{});
    var aw: std.Io.Writer.Allocating = .init(a);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try writeJson(&s);
    clear();
    try testing.expectEqual(@as(usize, 0), unread());
    const parsed = try std.json.parseFromSliceLeaky(std.json.Value, a, aw.writer.buffered(), .{});
    restoreJson(parsed);
    try testing.expectEqual(@as(usize, 1), unread());
    try testing.expect(std.mem.indexOf(u8, try takeAll(a), "hold the tree") != null);
}