Skip to content

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

Python
19.8 KB
Raw Blame
//! (#401) "Is VISIBLE PROSE flowing?" for the codex WebSocket reader — the WS
//! side of the signal the SSE reader takes straight from `partial_text`.
//!
//! Both feed the same http_stall.budgetMs, so this must mean EXACTLY what the
//! SSE signal means: too loose and a silently-reasoning turn is killed as a
//! stall (the round-2 regression), too tight and a mid-answer server death
//! waits four times as long as it does on SSE (the round-4 finding).
//!
//! SSE reads partial_text growth (until an item closes, ADR 0241), and on the `.responses` path
//! partial_text has TWO producers, both reached from agent_stream.streamSseLine:
//!
//!   1. the `response.output_text.delta` arm, whose `if (text.len == 0) return;`
//!      gate is why an EMPTY delta does not count. Reasoning deltas are handled
//!      above the append and `response.output_item.done` never reaches it, so a
//!      silent reasoning phase keeps the FULL pre-first-token budget on SSE —
//!      deliberately, since it legitimately runs minutes. → frameHasOutputText.
//!   2. `argLiveDelta` (called on EVERY line, before the text extraction) →
//!      ArgLive.feed → agent_argstream.emitArgText, which appends the streamed
//!      tool-ARGUMENT prose of a whitelisted call. Not an exotic path:
//!      attempt_completion is graff's ordinary final-answer tool, so a codex
//!      turn whose entire visible output is that prose streams only
//!      `response.function_call_arguments.delta` and never one output_text
//!      delta. → TokenSignal.
//!
//! The whitelist is NOT duplicated here: `argToolFor` is the same function
//! ArgLive.open classifies with, so the SSE and WS signals cannot drift.
//!
//! Lives beside agent_ws.zig (which is near the 600-line cap) the way
//! http_stall.zig lives beside http.zig, and is aliased back into agent_ws.

const std = @import("std");

const argstream = @import("agent_argstream.zig");
const argToolFor = argstream.argToolFor;
const outputIndex = argstream.outputIndex;

/// Producer 1: does this ws frame carry VISIBLE OUTPUT TEXT?
///
/// Frame ARRIVAL is not the signal: response.created / response.in_progress /
/// response.output_item.added land within milliseconds of the send, long before
/// the model has thought (and ping/pong never surfaces from readMessage at
/// all). Keying the budget on "a frame landed" tightens every WS turn to a
/// quarter budget from ~100ms in, so a high-effort turn reasoning silently past
/// that is killed as a stall, re-sent as a full re-anchor, stalled again, and
/// latched off WS for the session — while the identical turn survives on SSE.
///
/// Shape mirrors isStreamEnd: a cheap substring candidate, then an
/// authoritative parse, so a reasoning delta that merely QUOTES the event name
/// is not mistaken for one.
pub fn frameHasOutputText(gpa: std.mem.Allocator, frame: []const u8) bool {
    const ev = "response.output_text.delta";
    if (std.mem.indexOf(u8, frame, ev) == null) return false;
    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const v = std.json.parseFromSliceLeaky(std.json.Value, scratch.allocator(), frame, .{ .allocate = .alloc_always }) catch return false;
    if (v != .object) return false;
    const ty = v.object.get("type") orelse return false;
    if (ty != .string or !std.mem.eql(u8, ty.string, ev)) return false;
    const d = v.object.get("delta") orelse return false;
    return d == .string and d.string.len != 0;
}

/// ADR 0241: true for a Responses event that closes an output item, read off a
/// WS frame or an SSE `data:`/`event:` line. Prose tightens the between-lines
/// budget only until its item closes: the next item (a tool call composed
/// after a heads-up, say) can follow a silent think, and a quarter budget
/// there killed healthy turns as stalls and re-paid the whole generation.
/// Same shape as frameHasOutputText: a substring candidate, then a parse, so
/// prose that merely quotes the event name does not count.
pub fn closesItem(gpa: std.mem.Allocator, frame: []const u8) bool {
    const ev = "response.output_item.done";
    if (std.mem.indexOf(u8, frame, ev) == null) return false;
    var payload = std.mem.trim(u8, frame, " \t\r\n");
    if (std.mem.startsWith(u8, payload, "event:")) return std.mem.eql(u8, std.mem.trim(u8, payload["event:".len..], " \t"), ev);
    if (std.mem.startsWith(u8, payload, "data:")) payload = std.mem.trim(u8, payload["data:".len..], " \t");
    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const v = std.json.parseFromSliceLeaky(std.json.Value, scratch.allocator(), payload, .{ .allocate = .alloc_always }) catch return false;
    if (v != .object) return false;
    const ty = v.object.get("type") orelse return false;
    return ty == .string and std.mem.eql(u8, ty.string, ev);
}

/// ADR 0248: is the open output item a COMMENTARY message — the heads-up the
/// model writes before its tool calls? The server holds that message open
/// (no output_text.done, no output_item.done) until it releases the calls,
/// which it sends together once all of them are composed. Silence after
/// commentary is that composition, not a dead stream, so commentary prose
/// must not tighten the budget. A final answer (or a message with no phase)
/// still does. Fed WS frames and SSE `data:` lines alike.
pub const Phase = struct {
    commentary: bool = false,

    pub fn feed(self: *Phase, gpa: std.mem.Allocator, frame: []const u8) void {
        if (std.mem.indexOf(u8, frame, "response.output_item.") == null) return;
        if (closesItem(gpa, frame)) {
            self.commentary = false;
            return;
        }
        var payload = std.mem.trim(u8, frame, " \t\r\n");
        if (std.mem.startsWith(u8, payload, "data:")) payload = std.mem.trim(u8, payload["data:".len..], " \t");
        var scratch = std.heap.ArenaAllocator.init(gpa);
        defer scratch.deinit();
        const v = std.json.parseFromSliceLeaky(std.json.Value, scratch.allocator(), payload, .{ .allocate = .alloc_always }) catch return;
        if (v != .object) return;
        const ty = v.object.get("type") orelse return;
        if (ty != .string or !std.mem.eql(u8, ty.string, "response.output_item.added")) return;
        const item = v.object.get("item") orelse return;
        if (item != .object) return;
        const it = item.object.get("type") orelse return;
        const phase = item.object.get("phase") orelse {
            self.commentary = false;
            return;
        };
        self.commentary = it == .string and std.mem.eql(u8, it.string, "message") and
            phase == .string and std.mem.eql(u8, phase.string, "commentary");
    }
};

/// The turn's tokens-flowing signal: both producers, and the little bit of
/// state producer 2 needs (which output item is the open whitelisted call).
///
/// Producer 2 is keyed on the item, not the tool-argument bytes: SSE's ArgLive
/// starts appending a fraction of a frame later (once its scanner reaches the
/// `result`/`question` VALUE), so keying on the first non-empty argument delta
/// of a whitelisted call tightens at most one frame early on the same stream.
/// That direction is the safe one — the alternative is running a second copy of
/// the ArgLive scanner here, i.e. the drift this module exists to prevent.
pub const TokenSignal = struct {
    /// `output_index` of the open whitelisted (attempt_completion / ask_user)
    /// function call; -1 for none. The mirror of ArgLive.index, opened and
    /// closed by the same events argLiveDelta uses.
    arg_ix: i64 = -1,
    /// ADR 0241: prose is streaming in an item that has not closed yet. The WS
    /// read budget is tightened only while this holds.
    open: bool = false,
    /// ADR 0248: commentary prose flows without tightening (see Phase).
    phase: Phase = .{},

    /// True when a frame proves visible prose is flowing.
    pub fn flowing(self: *TokenSignal, gpa: std.mem.Allocator, frame: []const u8) bool {
        if (frameHasOutputText(gpa, frame)) return true;
        return self.argProse(gpa, frame);
    }

    /// Fed every frame. True when this frame is prose, which opens the gate
    /// unless it is commentary (ADR 0248); a frame that closes an output item
    /// shuts it again (ADR 0241).
    pub fn step(self: *TokenSignal, gpa: std.mem.Allocator, frame: []const u8) bool {
        self.phase.feed(gpa, frame);
        if (self.flowing(gpa, frame)) {
            if (!self.phase.commentary) self.open = true;
            return true;
        }
        if (closesItem(gpa, frame)) self.open = false;
        return false;
    }

    /// Producer 2. Tracks response.output_item.added/done to know WHICH item is
    /// a whitelisted call, then fires on that item's first non-empty argument
    /// delta. An ordinary tool's argument stream (edit_file, bash) prints
    /// nothing on SSE and so must leave the pre-first-token budget standing.
    fn argProse(self: *TokenSignal, gpa: std.mem.Allocator, frame: []const u8) bool {
        const arg_delta = "response.function_call_arguments.delta";
        // Cheap candidate filter, same shape as frameHasOutputText's: the two
        // item lifecycle events share the `response.output_item.` prefix.
        if (std.mem.indexOf(u8, frame, "response.output_item.") == null and
            std.mem.indexOf(u8, frame, arg_delta) == null) return false;
        var scratch = std.heap.ArenaAllocator.init(gpa);
        defer scratch.deinit();
        const v = std.json.parseFromSliceLeaky(std.json.Value, scratch.allocator(), frame, .{ .allocate = .alloc_always }) catch return false;
        if (v != .object) return false;
        const ty = v.object.get("type") orelse return false;
        if (ty != .string) return false;
        if (std.mem.eql(u8, ty.string, "response.output_item.added")) {
            const ix = outputIndex(v.object) orelse return false;
            const item = v.object.get("item") orelse return false;
            if (item != .object) return false;
            const it = item.object.get("type") orelse return false;
            if (it != .string or !std.mem.eql(u8, it.string, "function_call")) return false;
            const name = item.object.get("name") orelse return false;
            // Exactly ArgLive.open's gate: a non-whitelisted name opens nothing
            // (and cannot clobber an open index — output indices are unique).
            if (name == .string) {
                const t = argToolFor(name.string);
                // Visible prose only — rlm's `code` is speculated, not printed.
                if (t == .attempt_completion or t == .ask_user) self.arg_ix = ix;
            }
            return false;
        }
        if (std.mem.eql(u8, ty.string, "response.output_item.done")) {
            const ix = outputIndex(v.object) orelse return false;
            if (ix == self.arg_ix) self.arg_ix = -1; // ArgLive.close
            return false;
        }
        if (!std.mem.eql(u8, ty.string, arg_delta)) return false;
        const ix = outputIndex(v.object) orelse return false;
        if (ix != self.arg_ix) return false;
        const d = v.object.get("delta") orelse return false;
        return d == .string and d.string.len != 0;
    }
};

/// Responses WS `type:error` frames are terminal API responses, not transport
/// failures. The two known chain errors retain distinct labels for trace
/// diagnostics, but all three actions return the accumulated response body to
/// parseResponses instead of waiting for the peer's expected close frame.
pub const ErrorFrameAction = enum { none, api_error, retire, chain_lost };

pub fn errorFrameAction(gpa: std.mem.Allocator, frame: []const u8) ErrorFrameAction {
    // Error frames are rare. Parse only a cheap candidate so whitespace around
    // `type` is accepted and prose that merely quotes `"type":"error"` is not.
    if (std.mem.indexOf(u8, frame, "error") == null) return .none;
    var scratch = std.heap.ArenaAllocator.init(gpa);
    defer scratch.deinit();
    const v = std.json.parseFromSliceLeaky(std.json.Value, scratch.allocator(), frame, .{ .allocate = .alloc_always }) catch return .none;
    if (v != .object) return .none;
    const ty = v.object.get("type") orelse return .none;
    if (ty != .string or !std.mem.eql(u8, ty.string, "error")) return .none;
    const err = v.object.get("error");
    const code = if (err) |e| (if (e == .object) e.object.get("code") else null) else null;
    if (code) |c| if (c == .string) {
        // The server sends this right before closing a 25-minute-old socket.
        if (std.mem.eql(u8, c.string, "websocket_connection_limit_reached")) return .retire;
        // Our chain anchor is gone (evicted / never cached under store:false).
        if (std.mem.eql(u8, c.string, "previous_response_not_found")) return .chain_lost;
    };
    return .api_error;
}

/// The deadline for writing a frame of `frame_len` bytes.
///
/// NOT a flat head-sized budget: the frame most likely to sit under this guard
/// is the LARGEST one, because every recovery re-anchors with the full
/// conversation (closeCodexWs nulls codex_prev_id). A flat 30s over a ~1MB
/// re-anchor on a slow uplink is a false positive costing a transport failure,
/// and two of those latch SSE for the session. Policy: the head budget plus one
/// second per 64KB (a ~512 kbit/s floor, far below any link that can carry a
/// codex session), clamped to the read budget so the send guard can never
/// outlast the watchdog covering the reply.
pub fn sendDeadlineMs(frame_len: usize, head_ms: u64, stream_ms: u64) u64 {
    const grow: u64 = @as(u64, @intCast(frame_len / (64 * 1024))) *| 1000;
    return @min(head_ms +| grow, @max(head_ms, stream_ms));
}

test "errorFrameAction classifies every actual error frame and ignores quoted prose" {
    const a = std.testing.allocator;
    try std.testing.expectEqual(ErrorFrameAction.retire, errorFrameAction(a, "{\"type\":\"error\",\"error\":{\"code\":\"websocket_connection_limit_reached\"}}"));
    try std.testing.expectEqual(ErrorFrameAction.chain_lost, errorFrameAction(a, "{\"type\":\"error\",\"error\":{\"code\":\"previous_response_not_found\"}}"));
    try std.testing.expectEqual(ErrorFrameAction.api_error, errorFrameAction(a, "{ \"type\" : \"error\", \"error\" : {\"code\":\"invalid_request_error\"} }"));
    try std.testing.expectEqual(ErrorFrameAction.none, errorFrameAction(a, "{\"type\":\"response.output_text.delta\",\"delta\":\"quoted \\\"type\\\":\\\"error\\\"\"}"));
    try std.testing.expectEqual(ErrorFrameAction.none, errorFrameAction(a, "not json: error"));
}

/// Latch HTTPS SSE: 426, a stalled first handshake, or two transport failures.
/// Mid-stream HungRequest on a held socket is not a setup stall.
pub fn shouldLatchSse(setup_stall: bool, err: anyerror, failures: u8) bool {
    if (err == error.UpgradeRequired) return true;
    if (setup_stall) return true;
    return failures >= 2;
}

test "shouldLatchSse: 426 and connect stall latch now; 500 handshake still retries once" {
    try std.testing.expect(shouldLatchSse(false, error.UpgradeRequired, 1));
    try std.testing.expect(shouldLatchSse(true, error.HungRequest, 1));
    try std.testing.expect(!shouldLatchSse(false, error.HungRequest, 1));
    try std.testing.expect(!shouldLatchSse(false, error.HandshakeFailed, 1));
    try std.testing.expect(shouldLatchSse(false, error.HandshakeFailed, 2));
}

test "ADR 0241: prose tightens until its item closes; an ordinary tool's arguments do not reopen it" {
    const gpa = std.testing.allocator;
    var sig: TokenSignal = .{};
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.created\"}"));
    try std.testing.expect(!sig.open);
    try std.testing.expect(sig.step(gpa, "{\"type\":\"response.output_text.delta\",\"delta\":\"Checking the logs.\"}"));
    try std.testing.expect(sig.open);
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.done\",\"output_index\":0,\"item\":{\"type\":\"message\"}}"));
    try std.testing.expect(!sig.open);
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.added\",\"output_index\":1,\"item\":{\"type\":\"function_call\",\"name\":\"edit_file\"}}"));
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.function_call_arguments.delta\",\"output_index\":1,\"delta\":\"{\\\"path\\\":\"}"));
    try std.testing.expect(!sig.open);
    try std.testing.expect(sig.step(gpa, "{\"type\":\"response.output_text.delta\",\"delta\":\"Done.\"}"));
    try std.testing.expect(sig.open);
}

test "ADR 0241: closesItem reads WS frames and SSE lines, not prose that quotes the event name" {
    const gpa = std.testing.allocator;
    try std.testing.expect(closesItem(gpa, "{\"type\":\"response.output_item.done\",\"output_index\":0}"));
    try std.testing.expect(closesItem(gpa, "data: {\"type\":\"response.output_item.done\",\"output_index\":0}"));
    try std.testing.expect(closesItem(gpa, "event: response.output_item.done"));
    try std.testing.expect(!closesItem(gpa, "{\"type\":\"response.output_text.delta\",\"delta\":\"response.output_item.done\"}"));
    try std.testing.expect(!closesItem(gpa, "event: response.output_text.delta"));
    try std.testing.expect(!closesItem(gpa, "event: content_block_stop"));
}

test "ADR 0248: commentary prose flows without tightening; a final answer still tightens" {
    const gpa = std.testing.allocator;
    var sig: TokenSignal = .{};
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.added\",\"output_index\":1,\"item\":{\"type\":\"message\",\"phase\":\"commentary\"}}"));
    try std.testing.expect(sig.phase.commentary);
    // Visible prose (TTFT and the trace still see it) but the gate stays shut.
    try std.testing.expect(sig.step(gpa, "{\"type\":\"response.output_text.delta\",\"output_index\":1,\"delta\":\"Found the bugs; fixing them.\"}"));
    try std.testing.expect(!sig.open);
    // The server closes the message only when it releases the composed calls.
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.done\",\"output_index\":1,\"item\":{\"type\":\"message\",\"phase\":\"commentary\"}}"));
    try std.testing.expect(!sig.phase.commentary);
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.added\",\"output_index\":2,\"item\":{\"type\":\"message\",\"phase\":\"final_answer\"}}"));
    try std.testing.expect(sig.step(gpa, "{\"type\":\"response.output_text.delta\",\"output_index\":2,\"delta\":\"Done.\"}"));
    try std.testing.expect(sig.open);
}

test "ADR 0248: a message without a phase, and attempt_completion prose, tighten as before" {
    const gpa = std.testing.allocator;
    var sig: TokenSignal = .{};
    try std.testing.expect(!sig.step(gpa, "{\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"type\":\"message\"}}"));
    try std.testing.expect(sig.step(gpa, "{\"type\":\"response.output_text.delta\",\"output_index\":0,\"delta\":\"hi\"}"));
    try std.testing.expect(sig.open);
    var arg: TokenSignal = .{};
    try std.testing.expect(!arg.step(gpa, "{\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"type\":\"function_call\",\"name\":\"attempt_completion\"}}"));
    try std.testing.expect(arg.step(gpa, "{\"type\":\"response.function_call_arguments.delta\",\"output_index\":0,\"delta\":\"{\\\"result\\\":\\\"ok\"}"));
    try std.testing.expect(arg.open);
}

test "ADR 0248: Phase reads SSE data lines and ignores prose that quotes the phase" {
    const gpa = std.testing.allocator;
    var ph: Phase = .{};
    ph.feed(gpa, "data: {\"type\":\"response.output_item.added\",\"output_index\":0,\"item\":{\"type\":\"message\",\"phase\":\"commentary\"}}");
    try std.testing.expect(ph.commentary);
    ph.feed(gpa, "data: {\"type\":\"response.output_text.delta\",\"delta\":\"response.output_item.added commentary\"}");
    try std.testing.expect(ph.commentary);
    ph.feed(gpa, "data: {\"type\":\"response.output_item.done\",\"output_index\":0}");
    try std.testing.expect(!ph.commentary);
    ph.feed(gpa, "data: {\"type\":\"response.output_item.added\",\"output_index\":1,\"item\":{\"type\":\"function_call\",\"name\":\"edit_file\"}}");
    try std.testing.expect(!ph.commentary);
}