Skip to content

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

Python
13.1 KB
Raw Blame
//! Codex WS prewarm (openai/codex's `generate:false` prewarm_websocket, #codex-ws).
//!
//! Before the session's FIRST stream request on a fresh codex socket, send a
//! `response.create` with `generate:false` and no input items: the server
//! prepares the instructions+tools request state and returns a response id.
//! Turn 1 then chains onto it (`previous_response_id` + the user message), so
//! the big fixed prefix is ingested before the user's prompt instead of during
//! their wait. DeepWiki (openai/codex, `ModelClientSession.prewarm_websocket`):
//! best-effort connection setup — any failure falls through to a normal cold
//! turn; it is not an inference request and must not touch the meters.
//!
//! Kept out of agent_ws.zig (600-line cap). Own module so the frame shape and
//! the gate are testable without a socket.

const std = @import("std");
const Io = std.Io;
const main_mod = @import("main.zig");
const Agent = @import("agent.zig").Agent;
const ws = @import("ws.zig");
const http = @import("http.zig");
const body_responses = @import("agent_request_body_responses.zig");
const codex_chain = @import("codex_chain.zig");
const serde = @import("serde.zig");

const WatchdogFired = http.WatchdogFired;

/// Off by default: the warmup runs after the user's prompt, in series, and
/// measured slower on turn 1 than a cold turn (and no faster on turn 2).
/// GRAFF_WS_PREWARM=1 opts in.
pub var g_enabled = false;

/// Should this fresh connection prewarm? Codex, the ChatGPT plan or xAI
/// (on-socket chain), session start (nothing sent, no chain anchor), and not
/// under the full-resend experiment (seeding the chain would fight the flag's
/// premise).
pub fn eligible(self: *const Agent) bool {
    if (!g_enabled) return false;
    const brand = std.mem.eql(u8, self.provider.id, "codex") or std.mem.eql(u8, self.provider.id, "chatgpt-new") or
        (std.mem.eql(u8, self.provider.id, "xai") and codex_chain.g_xai_ws_chain);
    if (!brand) return false;
    if (codex_chain.g_force_full_resend) return false;
    return self.codex_ws != null and self.codex_prev_id == null and self.codex_sent_upto == 0;
}

/// Build the `{"type":"response.create",...generate:false}` frame. Same
/// properties (instructions, tools, reasoning effort) as the real turn, so the
/// chain fingerprint codex_chain.propsFor matches and turn 1 can chain.
pub fn buildFrame(self: *Agent, arena: std.mem.Allocator) ![]u8 {
    self.ws_prewarm = true;
    defer self.ws_prewarm = false;
    var out: std.Io.Writer.Allocating = .init(arena);
    var st: std.json.Stringify = .{ .writer = &out.writer };
    try st.beginObject();
    try st.objectField("type");
    try st.write("response.create");
    // buildBody writes the model before the Responses fields; this frame
    // must too, or the server rejects it as the 'None' model and the socket
    // is spent for the turn that follows.
    try st.objectField("model");
    try st.write(self.provider.model);
    try body_responses.write(self, &st, self.toolsJson(), false);
    try st.endObject();
    return out.toOwnedSlice();
}

/// Best-effort prewarm on a freshly dialed codex socket. Never fails the turn:
/// every failure path just leaves the chain state untouched so the real request
/// proceeds cold. On success the prewarm response id becomes the turn-1 chain
/// anchor (gpa-owned, same lifetime rule as codex_prev_id everywhere else).
/// xAI Responses WS spec: the response.create body must omit transport-only
/// fields (stream, background) — responses always stream back as socket
/// events. buildBody always writes `stream:true` (the SSE path requires it),
/// so the WS frame strips the trailing field. Codex's backend tolerates the
/// field; xAI's documents its omission.
pub fn stripTransportFields(frame: []u8) []u8 {
    const marker = ",\"stream\":true";
    if (std.mem.endsWith(u8, frame, marker ++ "}")) {
        // ...true,"stream":true}  →  ...true}  (move the closing brace over the marker)
        const cut = frame.len - marker.len - 1;
        frame[cut] = frame[frame.len - 1];
        return frame[0 .. cut + 1];
    }
    return frame;
}

/// Best-effort prewarm on a freshly dialed codex socket. Returns the frame to
/// send: the original, or the same frame with `previous_response_id` set to
/// the prewarm response id (all arena-owned — NOTHING here touches gpa-owned
/// chain state, so a turn whose response carries no id simply re-anchors on
/// turn 2, exactly as before). Every failure returns the original frame.
pub fn warm(self: *Agent, arena: std.mem.Allocator, client: *ws.WsClient, frame: []const u8) []const u8 {
    if (!eligible(self)) return frame;
    const tracer = self.tracer;
    const prewarm_frame = buildFrame(self, arena) catch return frame;
    // The frame is far under the 256KB SO_SNDBUF threshold agent_ws_signal
    // documents, so a blocking sendText copies into the socket buffer and
    // returns; the read half below is the bounded half.
    client.sendText(prewarm_frame) catch {
        if (tracer) |tr| tr.note("ws", "prewarm send failed — cold turn");
        return frame;
    };
    if (tracer) |tr| tr.note("ws", "prewarm sent");
    const id = awaitPrewarmId(self, arena, client) catch |e| {
        if (tracer) |tr| tr.note("ws", if (e == error.PrewarmRejected) "prewarm rejected — cold turn" else "prewarm no terminal — cold turn");
        return frame;
    };
    if (tracer) |tr| {
        var nbuf: [80]u8 = undefined;
        tr.note("ws", std.fmt.bufPrint(&nbuf, "prewarm ok — turn 1 chains onto {s}…", .{id[0..@min(id.len, 12)]}) catch "prewarm ok");
    }
    // Inject the chain seed into the real frame after the type field:
    // {"type":"response.create" ,"previous_response_id":"…", …}. Arena-owned;
    // a not-found rejection on turn 1 re-anchors through the existing ladder.
    const cut = std.mem.indexOf(u8, frame, ",\"") orelse return frame;
    return std.mem.concat(arena, u8, &.{
        frame[0..cut], ",\"previous_response_id\":\"", id, "\"", frame[cut..],
    }) catch frame;
}

/// Read frames until the prewarm's terminal event; returns response.id.
/// Bounded by the watchdog so a server that accepts the prewarm and goes
/// silent cannot park the user's turn behind it.
fn awaitPrewarmId(self: *Agent, arena: std.mem.Allocator, client: *ws.WsClient) ![]const u8 {
    var fbuf: std.ArrayList(u8) = .empty;
    defer fbuf.deinit(self.gpa);
    while (true) {
        const ReadDone = union(enum) { msg: ws.Error!ws.Opcode, stall: WatchdogFired };
        var rd_buf: [2]ReadDone = undefined;
        var rsel: Io.Select(ReadDone) = .init(self.io, &rd_buf);
        rsel.concurrent(.msg, readTask, .{ client, self.gpa, &fbuf }) catch return error.Watchdog;
        rsel.concurrent(.stall, @import("http.zig").deadlineStallTask, .{ self.io, false, @import("http.zig").head_stall_ms }) catch {
            const r = rsel.await() catch return error.Watchdog;
            rsel.cancelDiscard();
            _ = r.msg catch return error.Watchdog;
            continue;
        };
        const first = rsel.await() catch return error.Watchdog;
        rsel.cancelDiscard();
        switch (first) {
            .msg => |m| _ = m catch return error.Watchdog,
            .stall => return error.Watchdog,
        }
        if (fbuf.items.len == 0) continue;
        const v = std.json.parseFromSliceLeaky(std.json.Value, arena, fbuf.items, .{}) catch {
            fbuf.clearRetainingCapacity();
            continue;
        };
        const typv = v.object.get("type") orelse return error.NoId;
        if (typv != .string) return error.NoId;
        const t = typv.string;
        if (std.mem.eql(u8, t, "response.completed")) {
            const resp = v.object.get("response") orelse return error.NoId;
            const idv = resp.object.get("id") orelse return error.NoId;
            if (idv != .string or idv.string.len == 0) return error.NoId;
            return idv.string;
        }
        if (std.mem.eql(u8, t, "response.failed") or std.mem.eql(u8, t, "error")) {
            if (self.tracer) |tr| tr.note("ws", std.fmt.allocPrint(arena, "prewarm rejection: {s}", .{fbuf.items[0..@min(fbuf.items.len, 300)]}) catch "prewarm rejection");
            return error.PrewarmRejected;
        }
        fbuf.clearRetainingCapacity();
    }
}

fn readTask(client: *ws.WsClient, gpa: std.mem.Allocator, fbuf: *std.ArrayList(u8)) ws.Error!ws.Opcode {
    fbuf.clearRetainingCapacity();
    return client.readMessage(gpa, fbuf);
}

test "buildFrame: prewarm body has generate:false, empty input, no previous_response_id" {
    const stdt = std;
    var arena_state = stdt.heap.ArenaAllocator.init(stdt.testing.allocator);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var messages = stdt.json.Array.init(arena);
    try messages.append(try @import("messages.zig").textMessage(arena, "user", "hello"));
    var agent = Agent{
        .io = stdt.testing.io,
        .client = undefined,
        .provider = .{ .id = "codex", .kind = .responses, .auth = .bearer, .url = "https://chatgpt.com/backend-api/codex/responses", .api_key = "k", .model = "gpt-5.6", .context = 272_000 },
        .messages = messages,
        .sub = false,
        .label = "main",
        .out = null,
        .arena = arena,
        .gpa = stdt.testing.allocator,
    };
    const frame = try buildFrame(&agent, arena);
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "\"generate\":false") != null);
    // Without it the server answers "the 'None' model is not supported".
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "\"model\":\"gpt-5.6\"") != null);
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "\"input\":[]") != null);
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "previous_response_id") == null);
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "\"stream\":true") == null);
    try stdt.testing.expect(std.mem.indexOf(u8, frame, "\"instructions\"") != null);
    // The flag must not leak past the builder.
    try stdt.testing.expect(!agent.ws_prewarm);
}

test "stripTransportFields: WS frames omit the SSE-only stream field" {
    const stdt = std;
    const gpa = stdt.testing.allocator;
    const with_stream = try gpa.dupe(u8, "{\"type\":\"response.create\",\"model\":\"m\",\"input\":[],\"stream\":true}");
    defer gpa.free(with_stream);
    const stripped = stripTransportFields(with_stream);
    try stdt.testing.expect(std.mem.indexOf(u8, stripped, "stream") == null);
    try stdt.testing.expect(std.mem.endsWith(u8, stripped, "}"));
    try stdt.testing.expect(std.mem.indexOf(u8, stripped, "\"input\":[]") != null);
    // A frame without the field passes through unchanged.
    const clean = try gpa.dupe(u8, "{\"type\":\"response.create\",\"model\":\"m\"}");
    defer gpa.free(clean);
    try stdt.testing.expectEqualStrings(clean, stripTransportFields(clean));
}

test "eligible: xAI session start when chaining is on" {
    const stdt = std;
    try stdt.testing.expect(!g_enabled); // opt-in (GRAFF_WS_PREWARM=1)
    const saved_enabled = g_enabled;
    defer g_enabled = saved_enabled;
    g_enabled = true;
    var arena_state = stdt.heap.ArenaAllocator.init(stdt.testing.allocator);
    defer arena_state.deinit();
    var agent = Agent{
        .io = stdt.testing.io,
        .client = undefined,
        .provider = .{ .id = "xai", .kind = .responses, .auth = .bearer, .url = "https://api.x.ai/v1/responses", .api_key = "k", .model = "grok-4.6", .context = 500_000 },
        .messages = stdt.json.Array.init(arena_state.allocator()),
        .sub = false,
        .label = "main",
        .out = null,
        .arena = arena_state.allocator(),
        .gpa = stdt.testing.allocator,
    };
    var held: ws.WsClient = undefined;
    agent.codex_ws = &held;
    const saved = codex_chain.g_xai_ws_chain;
    defer codex_chain.g_xai_ws_chain = saved;
    codex_chain.g_xai_ws_chain = true;
    try stdt.testing.expect(eligible(&agent));
    codex_chain.g_xai_ws_chain = false;
    try stdt.testing.expect(!eligible(&agent));
}

test "eligible: codex session start only" {
    const stdt = std;
    try stdt.testing.expect(!g_enabled); // opt-in (GRAFF_WS_PREWARM=1)
    const saved_enabled = g_enabled;
    defer g_enabled = saved_enabled;
    g_enabled = true;
    var arena_state = stdt.heap.ArenaAllocator.init(stdt.testing.allocator);
    defer arena_state.deinit();
    var agent = Agent{
        .io = stdt.testing.io,
        .client = undefined,
        .provider = .{ .id = "codex", .kind = .responses, .auth = .bearer, .url = "https://chatgpt.com/backend-api/codex/responses", .api_key = "k", .model = "gpt-5.6", .context = 272_000 },
        .messages = stdt.json.Array.init(arena_state.allocator()),
        .sub = false,
        .label = "main",
        .out = null,
        .arena = arena_state.allocator(),
        .gpa = stdt.testing.allocator,
    };
    try stdt.testing.expect(!eligible(&agent)); // no socket yet
    var held: ws.WsClient = undefined;
    agent.codex_ws = &held;
    try stdt.testing.expect(eligible(&agent)); // fresh session start
    agent.codex_prev_id = "resp_1";
    try stdt.testing.expect(!eligible(&agent)); // chain already anchored
    agent.codex_prev_id = null;
    agent.codex_sent_upto = 2;
    try stdt.testing.expect(!eligible(&agent)); // mid-session re-anchor
}