Skip to content

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

Python
14.9 KB
Raw Blame
//! #1001 / #1007: idle roots start a turn when the durable room has unread
//! peer mail. Same latch on line REPL, TUI, and graff acp (GUI). JSONL drain
//! is the source of truth; Accord Unix (ADR 0134) is the standing live wake.
//! One auto-turn per new unread batch — inbox consume resets.

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

const peer_inbox = @import("peer_inbox.zig");
const peer_target = @import("peer_target.zig");
const presence = @import("presence.zig");
const presence_chan = @import("presence_chan.zig");

var last_woken_unread: usize = 0;
var last_placed_gen: u64 = 0;
var suppress_idle_wake: bool = false;
var waiting_for_input: bool = false;
var settled: bool = false;
var turn_busy: std.atomic.Value(bool) = .init(false);

pub fn resetForTest() void {
    last_woken_unread = 0;
    last_placed_gen = 0;
    suppress_idle_wake = false;
    waiting_for_input = false;
    settled = false;
    turn_busy.store(false, .release);
}

/// Root `runTurn` latch. Idle auto-turn (#1001 / #1007) and mid-turn
/// `deliverInbound` injects stay off while a prompt is in flight (#1136).
pub fn noteTurnStart() void {
    turn_busy.store(true, .release);
}

pub fn noteTurnEnd() void {
    turn_busy.store(false, .release);
}

pub fn isBusy() bool {
    return turn_busy.load(.acquire);
}

/// Accepted `attempt_completion` ends the task the same way a final answer
/// does (ADR 0311): room mail stays parked for the next human prompt, and
/// only mail addressed to this session can start a turn. Which of the two a
/// model happens to end with must not decide whether a peer's follow-up is
/// heard.
pub fn noteCompletion() void {
    settled = true;
}

/// A root turn ended with an ordinary final answer (#1137). The human task
/// is done: mail posted to the folder's room is ambient coordination and no
/// longer starts a turn on its own. It stays parked and readable, and the
/// next human prompt sees it. Mail addressed to this session (a DM, or the
/// user's own `/tell`) is an explicit request and still wakes, so peers can
/// still hand work over.
pub fn noteFinalAnswer() void {
    settled = true;
}

/// The last task ended (final answer or attempt_completion) and no human
/// prompt has come since.
pub fn isSettled() bool {
    return settled;
}

/// Whether the parked mail at or after `from` may start a turn by itself.
fn mayStartTurn(from: usize) bool {
    if (settled) return peer_inbox.anyAddressedNeedsTurnFrom(from);
    return peer_inbox.anyNeedsTurnFrom(from);
}

/// Mail at or after `from` is held for the next human prompt: the last task
/// ended with an answer and none of it is addressed to this session.
pub fn ambientHeld(from: usize) bool {
    return settled and !peer_inbox.anyAddressedNeedsTurnFrom(from);
}

/// A handoff waits for human input without completing a goal. Peer mail
/// stays readable, but cannot immediately reopen the yielded turn.
pub fn noteHandoff() void {
    suppress_idle_wake = true;
    waiting_for_input = true;
}

pub fn waitingForInput() bool {
    return waiting_for_input;
}

/// A later human prompt re-opens idle auto-turn.
pub fn noteHumanPrompt() void {
    suppress_idle_wake = false;
    waiting_for_input = false;
    settled = false;
}

pub fn idleWakeSuppressed() bool {
    return suppress_idle_wake;
}

pub fn markPlaced(gen: u64) void {
    last_placed_gen = gen;
    last_woken_unread = peer_inbox.unread();
}

pub fn placedGeneration() u64 {
    return last_placed_gen;
}

fn ingest(io: Io, arena: Allocator) void {
    const local = presence.drainChannel(io, arena);
    const device = presence.drainDevice(io, arena);
    const own = presence.ownSession();
    var tree: std.ArrayList(presence.Message) = .empty;
    for (local) |m| {
        if (peer_target.treeHears(m, own)) tree.append(arena, m) catch break;
    }
    var heard: std.ArrayList(presence.Message) = .empty;
    for (device) |m| {
        if (peer_target.deviceHears(m, own)) heard.append(arena, m) catch break;
    }
    _ = peer_inbox.parkHeard(tree.items, heard.items);
}

/// Idle TUI auto-turn. Null when nothing new is parked. Uses a scratch
/// buffer so a spent Agent arena cannot hide new JSONL. Does not inject
/// history — `runTurn`'s deliverInbound handles leftover room bytes.
pub fn takeIdleWake(io: Io, buf: []u8) ?[]const u8 {
    if (isBusy()) return null;
    var scratch: [64 * 1024]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&scratch);
    const arena = fba.allocator();
    ingest(io, arena);
    if (@import("daddy.zig").takeIdleText(arena, buf)) |t| {
        last_woken_unread = peer_inbox.unread();
        return t;
    }
    if (suppress_idle_wake) return null;
    const n = peer_inbox.unread();
    if (n == 0 or n <= last_woken_unread) return null;
    // #1137: fyi-only news stays parked for the next turn; it starts none.
    // After a final answer only mail addressed to this session does.
    if (!mayStartTurn(last_woken_unread)) return null;
    last_woken_unread = n;
    const wake = peer_inbox.formatWake(arena);
    if (wake.len == 0) return null;
    const copy = @min(wake.len, buf.len);
    @memcpy(buf[0..copy], wake[0..copy]);
    return buf[0..copy];
}

/// `action=inbox` consumed the batch — a later peer can wake again.
pub fn noteInboxConsumed() void {
    last_woken_unread = 0;
    last_placed_gen = 0;
}

test "#1001 idle wake fires once per new unread batch" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    const io = std.testing.io;
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var buf: [256]u8 = undefined;
    try std.testing.expect(takeIdleWake(io, &buf) == null);

    const msg: presence_chan.Message = .{
        .from_pid = 2,
        .from_start = 1,
        .from_session = "s-peer",
        .text = "hold gui/src",
        .to = "s-me",
    };
    try std.testing.expectEqual(@as(usize, 1), peer_inbox.parkHeard(&.{msg}, &.{}));
    const first = takeIdleWake(io, &buf) orelse return error.ExpectedWake;
    try std.testing.expect(std.mem.indexOf(u8, first, "[peer]") != null);
    try std.testing.expect(std.mem.indexOf(u8, first, "inbox") != null);
    try std.testing.expectEqual(@as(usize, 1), peer_inbox.unread());
    try std.testing.expect(takeIdleWake(io, &buf) == null);

    _ = try peer_inbox.takeAll(arena);
    noteInboxConsumed();
    try std.testing.expect(takeIdleWake(io, &buf) == null);
}

test "ADR 0311: after attempt_completion only mail addressed to this session wakes" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    var buf: [256]u8 = undefined;
    noteCompletion();
    try std.testing.expect(isSettled() and !idleWakeSuppressed());
    _ = peer_inbox.parkHeard(&.{.{ .from_pid = 2, .from_start = 1, .from_session = "s-peer", .text = "room chatter" }}, &.{});
    try std.testing.expect(takeIdleWake(std.testing.io, &buf) == null);
    const msg: presence_chan.Message = .{
        .from_pid = 2,
        .from_start = 1,
        .from_session = "s-peer",
        .text = "hold the tree",
        .to = "s-me",
    };
    _ = peer_inbox.parkHeard(&.{msg}, &.{});
    const wake = takeIdleWake(std.testing.io, &buf) orelse return error.ExpectedAddressedWake;
    try std.testing.expect(std.mem.indexOf(u8, wake, "[peer]") != null);
}

test "#1136 idle wake is silent while a root turn is in flight" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    var buf: [256]u8 = undefined;
    const msg: presence_chan.Message = .{
        .from_pid = 2,
        .from_start = 1,
        .from_session = "s-peer",
        .text = "hold the tree",
        .to = "s-me",
    };
    _ = peer_inbox.parkHeard(&.{msg}, &.{});
    noteTurnStart();
    try std.testing.expect(isBusy());
    try std.testing.expect(takeIdleWake(std.testing.io, &buf) == null);
    noteTurnEnd();
    const wake = takeIdleWake(std.testing.io, &buf) orelse return error.ExpectedWakeAfterIdle;
    try std.testing.expect(std.mem.indexOf(u8, wake, "[peer]") != null);
}

test "#1137 same unread generation does not idle-wake twice" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    var buf: [256]u8 = undefined;
    const msg: presence_chan.Message = .{
        .from_pid = 2,
        .from_start = 1,
        .from_session = "s-peer",
        .text = "hold the tree",
        .to = "s-me",
    };
    _ = peer_inbox.parkHeard(&.{msg}, &.{});
    try std.testing.expect(takeIdleWake(std.testing.io, &buf) != null);
    try std.testing.expect(takeIdleWake(std.testing.io, &buf) == null);
}

test "#1001 more mail after a wake can fire again" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    const io = std.testing.io;
    var buf: [256]u8 = undefined;
    const a: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "one" };
    const b: presence_chan.Message = .{ .from_pid = 3, .from_start = 1, .from_session = "s-b", .text = "two" };
    _ = peer_inbox.parkHeard(&.{a}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) != null);
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    _ = peer_inbox.parkHeard(&.{b}, &.{});
    const again = takeIdleWake(io, &buf) orelse return error.ExpectedSecond;
    try std.testing.expect(std.mem.indexOf(u8, again, "[peer]") != null);
}

test "#1137 fyi mail stays parked without a turn; a request after it wakes" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    const io = std.testing.io;
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var buf: [256]u8 = undefined;
    const fyi: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "[fyi] I only touch gui/src" };
    const fyi2: presence_chan.Message = .{ .from_pid = 3, .from_start = 1, .from_session = "s-b", .text = "  [fyi] docs done" };
    _ = peer_inbox.parkHeard(&.{ fyi, fyi2 }, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    try std.testing.expectEqual(@as(usize, 2), peer_inbox.unread()); // still readable
    const ask: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "can you rerun the tests?" };
    _ = peer_inbox.parkHeard(&.{ask}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) != null);
    // An fyi after the woken batch does not wake again.
    _ = peer_inbox.parkHeard(&.{fyi}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    const read = try peer_inbox.takeAll(arena_state.allocator());
    try std.testing.expect(std.mem.indexOf(u8, read, "[fyi] updates need no reply") != null);
}

test "#1137 room mail after an ordinary final answer stays parked; a DM still wakes" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    const io = std.testing.io;
    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena_state.deinit();
    var buf: [256]u8 = undefined;
    // The human's task ended with an ordinary answer, not attempt_completion.
    noteTurnStart();
    noteFinalAnswer();
    noteTurnEnd();
    try std.testing.expect(!idleWakeSuppressed());
    // Two unmarked scope updates posted to the folder's room, read in between.
    const scope: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "I only touch gui/src" };
    _ = peer_inbox.parkHeard(&.{scope}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    try std.testing.expectEqual(@as(usize, 1), peer_inbox.unread()); // still readable
    _ = try peer_inbox.takeAll(arena_state.allocator());
    noteInboxConsumed();
    const other: presence_chan.Message = .{ .from_pid = 3, .from_start = 1, .from_session = "s-b", .text = "docs are mine this hour" };
    _ = peer_inbox.parkHeard(&.{other}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    // A request addressed to this session is explicit: it starts a turn.
    const ask: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "can you rerun the parser tests?", .to = "s-me" };
    _ = peer_inbox.parkHeard(&.{ask}, &.{});
    const wake = takeIdleWake(io, &buf) orelse return error.ExpectedDirectWake;
    try std.testing.expect(std.mem.indexOf(u8, wake, "[peer]") != null);
    // An fyi DM never does.
    _ = peer_inbox.takeAll(arena_state.allocator()) catch unreachable;
    noteInboxConsumed();
    const fyi_dm: presence_chan.Message = .{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "[fyi] done with the parser", .to = "s-me" };
    _ = peer_inbox.parkHeard(&.{fyi_dm}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) == null);
    // The next human prompt starts a new task: room mail can wake again.
    noteHumanPrompt();
    _ = peer_inbox.parkHeard(&.{scope}, &.{});
    try std.testing.expect(takeIdleWake(io, &buf) != null);
}

test "#1137 a turn that ended without an answer still wakes on room mail" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    var buf: [256]u8 = undefined;
    // Interrupted or failed: no final answer, nothing settled.
    noteTurnStart();
    noteTurnEnd();
    _ = peer_inbox.parkHeard(&.{.{ .from_pid = 2, .from_start = 1, .from_session = "s-a", .text = "can someone rerun the tests?" }}, &.{});
    try std.testing.expect(takeIdleWake(std.testing.io, &buf) != null);
}

test "#1137 every root final answer settles the turn" {
    const src = @embedFile("agent_turn.zig");
    const start = std.mem.indexOf(u8, src, "if (done) |final_text| {") orelse return error.MissingPin;
    const body = src[start..];
    // The ordinary final settles once, right before it returns the answer.
    try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, body, "settleFinal(self);"));
    const settle = std.mem.indexOf(u8, body, "settleFinal(self);").?;
    try std.testing.expect(std.mem.indexOfPos(u8, body, settle, "return review_deadline.finish(text);") != null);
    try std.testing.expect(std.mem.indexOf(u8, src, "noteFinalAnswer()") != null);
}

test "daddy idle wake fires after attempt_completion" {
    peer_inbox.resetForTest();
    resetForTest();
    defer {
        peer_inbox.resetForTest();
        resetForTest();
    }
    var buf: [256]u8 = undefined;
    noteCompletion();
    _ = peer_inbox.parkHeard(&.{.{ .from_session = "s-dad", .text = "[daddy] switch to the tests" }}, &.{});
    const wake = takeIdleWake(std.testing.io, &buf) orelse return error.ExpectedDaddyAfterCompletion;
    try std.testing.expect(std.mem.indexOf(u8, wake, "[daddy]") != null);
}