Skip to content

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

Python
24.2 KB
Raw Blame
//! The wire half of hosted compaction (ADR 0252): graff's provider-shaped
//! history to the gateway's neutral transcript, and the reply back onto it.
//! Pure — no Agent, no network — so every wire format's mapping is pinned by
//! fixtures (gateway_compact_tests.zig).
//!
//! Out: consecutive items of one side fold into one neutral message — user
//! prompts, harness notes and tool results on one side; assistant text, calls
//! and reasoning on the other — and each message remembers the native range
//! it came from. In: the endpoint's per-call decisions are applied to the
//! NATIVE items by call id. Nothing is rebuilt from the neutral copy, so
//! reasoning, images and provider metadata stay as they were; a hybrid summary
//! replaces only the native range it summarized.

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

const sanitizeUtf8 = @import("messages.zig").sanitizeUtf8;

/// The endpoint's own cap on one transcript.
pub const max_messages = 2000;
/// Newest messages the hybrid summary keeps verbatim: the endpoint's default,
/// which its summary step applies whatever the request says.
pub const recent_kept = 6;

pub const Role = enum { user, assistant };
pub const Use = struct { id: []const u8, name: []const u8, input: Value = .null };
pub const Result = struct { id: []const u8, text: []const u8 = "", is_error: bool = false };

pub const Msg = struct {
    role: Role,
    /// The native items [lo, hi) this message folds.
    lo: usize,
    hi: usize,
    text: []const u8 = "",
    uses: []const Use = &.{},
    results: []const Result = &.{},
};

const Builder = struct {
    a: Allocator,
    /// Call/result ids only: no text, no argument parsing (pair checks).
    ids_only: bool = false,
    out: std.ArrayList(Msg) = .empty,
    open: ?Msg = null,
    text: std.ArrayList(u8) = .empty,
    uses: std.ArrayList(Use) = .empty,
    results: std.ArrayList(Result) = .empty,

    fn close(b: *Builder) !void {
        var m = b.open orelse return;
        m.text = try b.text.toOwnedSlice(b.a);
        m.uses = try b.uses.toOwnedSlice(b.a);
        m.results = try b.results.toOwnedSlice(b.a);
        try b.out.append(b.a, m);
        b.open = null;
    }

    fn addText(b: *Builder, s: []const u8) !void {
        if (b.ids_only or s.len == 0) return;
        if (b.text.items.len > 0) try b.text.append(b.a, '\n');
        try b.text.appendSlice(b.a, sanitizeUtf8(b.a, s));
    }

    fn use(b: *Builder, id: ?[]const u8, name: ?[]const u8, input: ?Value, wrap_as: []const u8) !void {
        const call_id = id orelse return;
        const args: Value = if (b.ids_only) .null else try argsObject(b.a, input, wrap_as);
        try b.uses.append(b.a, .{ .id = call_id, .name = name orelse "tool", .input = args });
    }

    fn result(b: *Builder, id: ?[]const u8, payload: ?Value, is_error: bool) !void {
        const call_id = id orelse return;
        const text = if (b.ids_only) "" else sanitizeUtf8(b.a, try textOf(b.a, payload orelse .null));
        try b.results.append(b.a, .{ .id = call_id, .text = text, .is_error = is_error });
    }
};

fn str(o: ObjectMap, key: []const u8) ?[]const u8 {
    const v = o.get(key) orelse return null;
    return if (v == .string) v.string else null;
}

fn eql(a: []const u8, b: []const u8) bool {
    return std.mem.eql(u8, a, b);
}

fn errorFlag(o: ObjectMap) bool {
    const v = o.get("is_error") orelse o.get("isError") orelse return false;
    return v == .bool and v.bool;
}

/// Which side an item speaks for. Typed items (Responses, Interactions) are
/// the model's unless they carry a result or a prompt; role messages follow
/// their role, with tool results and harness notes on the user side.
fn itemRole(item: Value) ?Role {
    if (item != .object) return null;
    const o = item.object;
    if (str(o, "type")) |t| {
        if (eql(t, "function_call_output") or eql(t, "custom_tool_call_output") or
            eql(t, "function_result") or eql(t, "user_input")) return .user;
        if (!eql(t, "message")) return .assistant; // calls, reasoning, thought, model_output, opaque state
    }
    const role = str(o, "role") orelse return null;
    return if (eql(role, "assistant")) .assistant else .user;
}

/// Joined text of a string, a text-bearing object, or an array of parts.
/// Images and other non-text parts contribute nothing.
pub fn textOf(a: Allocator, v: Value) ![]const u8 {
    switch (v) {
        .string => |s| return s,
        .object => |o| return str(o, "text") orelse "",
        .array => |arr| {
            var out: std.ArrayList(u8) = .empty;
            for (arr.items) |part| {
                const t = switch (part) {
                    .string => |s| s,
                    .object => |o| str(o, "text") orelse "",
                    else => "",
                };
                if (t.len == 0) continue;
                if (out.items.len > 0) try out.append(a, '\n');
                try out.appendSlice(a, t);
            }
            return out.items;
        },
        else => return "",
    }
}

/// The endpoint takes a call's input as a JSON object: Chat/Responses carry a
/// string of JSON, a freeform tool a raw string, and either may not parse.
fn argsObject(a: Allocator, v: ?Value, wrap_as: []const u8) !Value {
    const raw = v orelse return .{ .object = .empty };
    switch (raw) {
        .object => return raw,
        .null => return .{ .object = .empty },
        .string => |s| {
            if (std.json.parseFromSliceLeaky(Value, a, s, .{ .allocate = .alloc_always })) |parsed| {
                if (parsed == .object) return parsed;
            } else |_| {}
        },
        else => {},
    }
    var o: ObjectMap = .empty;
    try o.put(a, wrap_as, raw);
    return .{ .object = o };
}

fn absorbBlock(b: *Builder, block: Value) !void {
    if (block == .string) return b.addText(block.string);
    if (block != .object) return;
    const o = block.object;
    const t = str(o, "type") orelse return;
    if (eql(t, "text") or eql(t, "input_text") or eql(t, "output_text")) return b.addText(str(o, "text") orelse "");
    if (eql(t, "tool_use")) return b.use(str(o, "id"), str(o, "name"), o.get("input"), "input");
    if (eql(t, "tool_result")) return b.result(str(o, "tool_use_id"), o.get("content"), errorFlag(o));
}

fn absorb(b: *Builder, item: Value) !void {
    if (item != .object) return;
    const o = item.object;
    if (str(o, "type")) |t| {
        if (eql(t, "function_call")) return b.use(str(o, "call_id") orelse str(o, "id"), str(o, "name"), o.get("arguments"), "arguments");
        if (eql(t, "custom_tool_call")) return b.use(str(o, "call_id"), str(o, "name"), o.get("input"), "input");
        if (eql(t, "function_call_output") or eql(t, "custom_tool_call_output")) return b.result(str(o, "call_id"), o.get("output"), false);
        if (eql(t, "function_result")) return b.result(str(o, "call_id"), o.get("result"), errorFlag(o));
        if (eql(t, "user_input") or eql(t, "model_output") or eql(t, "message")) {
            if (b.ids_only) return;
            return b.addText(try textOf(b.a, o.get("content") orelse .null));
        }
        return; // reasoning, thought, opaque provider state: nothing readable
    }
    const role = str(o, "role") orelse return;
    if (eql(role, "tool")) {
        // OpenAI Chat has no error bit; graff writes failures with this prefix.
        const content = o.get("content") orelse Value.null;
        const failed = content == .string and std.mem.startsWith(u8, content.string, "[error] ");
        return b.result(str(o, "tool_call_id"), content, failed);
    }
    if (o.get("content")) |content| switch (content) {
        .string => |s| try b.addText(s),
        .array => |arr| for (arr.items) |block| try absorbBlock(b, block),
        else => {},
    };
    if (o.get("tool_calls")) |calls| if (calls == .array) for (calls.array.items) |call| {
        if (call != .object) continue;
        const f = call.object.get("function") orelse continue;
        if (f != .object) continue;
        try b.use(str(call.object, "id"), str(f.object, "name"), f.object.get("arguments"), "arguments");
    };
}

fn fold(a: Allocator, items: []const Value, ids_only: bool) ![]const Msg {
    var b: Builder = .{ .a = a, .ids_only = ids_only };
    for (items, 0..) |item, i| {
        const role = itemRole(item) orelse if (b.open) |m| m.role else Role.user;
        if (b.open == null or b.open.?.role != role) {
            try b.close();
            b.open = .{ .role = role, .lo = i, .hi = i };
        }
        b.open.?.hi = i + 1;
        try absorb(&b, item);
    }
    try b.close();
    return b.out.items;
}

/// Native history → neutral messages. The ranges are contiguous and cover
/// every item, so each native item belongs to exactly one message.
pub fn transcript(a: Allocator, items: []const Value) ![]const Msg {
    return fold(a, items, false);
}

/// The POST /v1/compact body.
pub fn request(a: Allocator, msgs: []const Msg, model: []const u8, goal: ?[]const u8) ![]const u8 {
    const WireUse = struct { tool_use_id: []const u8, tool: []const u8, input: Value };
    const WireResult = struct { tool_use_id: []const u8, text: []const u8, isError: ?bool };
    const WireMsg = struct { role: []const u8, text: []const u8, toolUses: []const WireUse, toolResults: []const WireResult };
    const out = try a.alloc(WireMsg, msgs.len);
    for (msgs, out) |m, *w| {
        const uses = try a.alloc(WireUse, m.uses.len);
        for (m.uses, uses) |u, *x| x.* = .{ .tool_use_id = u.id, .tool = u.name, .input = u.input };
        const results = try a.alloc(WireResult, m.results.len);
        for (m.results, results) |r, *x| x.* = .{ .tool_use_id = r.id, .text = r.text, .isError = if (r.is_error) true else null };
        w.* = .{ .role = @tagName(m.role), .text = m.text, .toolUses = uses, .toolResults = results };
    }
    var aw: std.Io.Writer.Allocating = .init(a);
    const body = .{ .model = model, .mode = "hybrid", .goal = goal, .messages = out };
    try std.json.Stringify.value(body, .{ .emit_null_optional_fields = false }, &aw.writer);
    return aw.writer.buffered();
}

pub const Action = enum { keep, drop_result, drop_call };
pub const Decisions = std.StringHashMapUnmanaged(Action);

pub const Reply = struct {
    decisions: Decisions = .empty,
    /// The endpoint's transcript after compaction, for validation only.
    messages: []const Value = &.{},
    summarized: bool = false,
    /// The spliced summary without the endpoint's header line.
    summary: []const u8 = "",
};

pub fn parseReply(a: Allocator, root: Value) !Reply {
    if (root != .object) return error.UnexpectedReply;
    const msgs = root.object.get("messages") orelse return error.UnexpectedReply;
    const decisions = root.object.get("decisions") orelse return error.UnexpectedReply;
    if (msgs != .array or decisions != .array) return error.UnexpectedReply;
    var reply: Reply = .{ .messages = msgs.array.items };
    for (decisions.array.items) |d| {
        if (d != .object) return error.UnexpectedReply;
        const id = str(d.object, "tool_use_id") orelse return error.UnexpectedReply;
        const action = std.meta.stringToEnum(Action, str(d.object, "action") orelse "") orelse return error.UnexpectedReply;
        try reply.decisions.put(a, id, action);
    }
    if (root.object.get("stats")) |stats| {
        if (stats == .object) if (stats.object.get("summarized")) |v| {
            reply.summarized = v == .bool and v.bool;
        };
    }
    if (reply.summarized) {
        if (reply.messages.len < 2 or reply.messages[1] != .object) return error.UnexpectedReply;
        const text = str(reply.messages[1].object, "text") orelse return error.UnexpectedReply;
        const body = if (std.mem.indexOfScalar(u8, text, '\n')) |nl| text[nl + 1 ..] else text;
        reply.summary = std.mem.trim(u8, body, " \t\r\n");
        if (reply.summary.len == 0) return error.UnexpectedReply;
    }
    return reply;
}

fn act(d: *const Decisions, id: ?[]const u8) Action {
    return d.get(id orelse return .keep) orelse .keep;
}

/// The endpoint's rule: a message survives unless compaction touched it and
/// left no text, call, or result behind.
fn survives(m: Msg, d: *const Decisions) bool {
    var touched = false;
    var left = m.text.len > 0;
    for (m.uses) |u| {
        if (act(d, u.id) == .drop_call) touched = true else left = true;
    }
    for (m.results) |r| switch (act(d, r.id)) {
        .drop_call => touched = true,
        .drop_result => {
            touched = true;
            left = true;
        },
        .keep => left = true,
    };
    return !touched or left;
}

fn sameIds(listed: ?Value, comptime T: type, mine: []const T, d: *const Decisions) bool {
    const arr = if (listed) |v| (if (v == .array) v.array.items else return false) else &[_]Value{};
    var k: usize = 0;
    for (mine) |x| {
        if (act(d, x.id) == .drop_call) continue;
        if (k >= arr.len or arr[k] != .object) return false;
        const id = str(arr[k].object, "tool_use_id") orelse return false;
        if (!eql(id, x.id)) return false;
        k += 1;
    }
    return k == arr.len;
}

/// Is `r` (from the reply) message `m` after the decisions? Text is compared
/// byte for byte: the endpoint never rewrites it.
fn matches(r: Value, m: Msg, d: *const Decisions) bool {
    if (r != .object) return false;
    const role = str(r.object, "role") orelse return false;
    if (!eql(role, @tagName(m.role))) return false;
    if (!eql(str(r.object, "text") orelse "", m.text)) return false;
    return sameIds(r.object.get("toolUses"), Use, m.uses, d) and
        sameIds(r.object.get("toolResults"), Result, m.results, d);
}

fn useAt(msgs: []const Msg, id: []const u8) ?usize {
    for (msgs, 0..) |m, j| for (m.uses) |u| if (eql(u.id, id)) return j;
    return null;
}

pub fn msgAt(msgs: []const Msg, native: usize) ?usize {
    for (msgs, 0..) |m, j| if (native >= m.lo and native < m.hi) return j;
    return null;
}

pub const Plan = struct {
    /// Per neutral message: kept (with its per-call decisions applied).
    keep: []bool,
    /// The neutral message the summary note goes before; null = no summary.
    note_before: ?usize = null,
};

/// Check the reply against what the decisions imply, then decide which
/// neutral messages stay. A summarized reply is [first, summary, newest k]:
/// k is at least recent_kept, more when the endpoint moved its cut back over
/// a call/result pair. The cut also moves back here over any call a kept
/// result answers (a result without its call is rejected by every wire), and
/// `opening` — an unresolved turn's opening prompt (#581) — stays verbatim.
pub fn plan(a: Allocator, msgs: []const Msg, reply: *const Reply, opening: ?usize) !Plan {
    const d = &reply.decisions;
    var left: std.ArrayList(usize) = .empty;
    for (msgs, 0..) |m, j| if (survives(m, d)) try left.append(a, j);
    const keep = try a.alloc(bool, msgs.len);
    @memset(keep, true);
    if (!reply.summarized) {
        if (reply.messages.len != left.items.len) return error.UnexpectedReply;
        for (left.items, reply.messages) |j, r| if (!matches(r, msgs[j], d)) return error.UnexpectedReply;
        return .{ .keep = keep };
    }
    // At least two messages summarized between the first and the kept tail.
    if (reply.messages.len < recent_kept + 2 or left.items.len < reply.messages.len + 1) return error.UnexpectedReply;
    const head = left.items[0];
    const tail = left.items[left.items.len - (reply.messages.len - 2) ..];
    if (!matches(reply.messages[0], msgs[head], d)) return error.UnexpectedReply;
    for (tail, reply.messages[2..]) |j, r| if (!matches(r, msgs[j], d)) return error.UnexpectedReply;
    var cut = tail[0];
    var moved = true;
    while (moved) {
        moved = false;
        for (msgs[cut..]) |m| for (m.results) |r| {
            const j = useAt(msgs, r.id) orelse continue;
            if (j > head and j < cut) {
                cut = j;
                moved = true;
            }
        };
    }
    @memset(keep, false);
    keep[head] = true;
    @memset(keep[cut..], true);
    if (opening) |t| {
        if (msgAt(msgs, t)) |j| keep[j] = keep[j] or j > head;
    }
    var note_before: ?usize = null;
    for (keep[head + 1 ..], head + 1..) |k, j| if (k) {
        note_before = j;
        break;
    };
    return .{ .keep = keep, .note_before = note_before orelse return error.UnexpectedReply };
}

fn cloneObject(a: Allocator, o: ObjectMap) !ObjectMap {
    var c: ObjectMap = .empty;
    try c.ensureTotalCapacity(a, o.count());
    var it = o.iterator();
    while (it.next()) |e| c.putAssumeCapacity(e.key_ptr.*, e.value_ptr.*);
    return c;
}

fn withField(a: Allocator, o: ObjectMap, key: []const u8, v: Value) !Value {
    var c = try cloneObject(a, o);
    try c.put(a, key, v);
    return .{ .object = c };
}

const Shape = enum { string, parts };

/// A result payload per its decision: gone with its call, shrunk to a stub,
/// or untouched. Null removes the item.
fn shrink(a: Allocator, o: ObjectMap, field: []const u8, action: Action, removable: bool, shape: Shape, stubber: anytype) !?Value {
    if (action == .keep) return .{ .object = o };
    if (action == .drop_call and removable) return null;
    const full = try textOf(a, o.get(field) orelse .null);
    const stub = stubber.stub(a, full);
    if (stub.len >= full.len) return .{ .object = o };
    const payload: Value = switch (shape) {
        .string => .{ .string = stub },
        .parts => blk: {
            var part: ObjectMap = .empty;
            try part.put(a, "type", .{ .string = "text" });
            try part.put(a, "text", .{ .string = stub });
            var parts = std.json.Array.init(a);
            try parts.append(.{ .object = part });
            break :blk .{ .array = parts };
        },
    };
    return try withField(a, o, field, payload);
}

fn shrinkBlocks(a: Allocator, o: ObjectMap, d: *const Decisions, removable: bool, stubber: anytype) !?Value {
    const content = o.get("content") orelse return .{ .object = o };
    if (content != .array) return .{ .object = o };
    var blocks = std.json.Array.init(a);
    var changed = false;
    for (content.array.items) |block| {
        const is_result = block == .object and eql(str(block.object, "type") orelse "", "tool_result");
        const action = if (is_result) act(d, str(block.object, "tool_use_id")) else .keep;
        if (action == .keep) {
            try blocks.append(block);
            continue;
        }
        changed = true;
        if (try shrink(a, block.object, "content", action, removable, .string, stubber)) |v| try blocks.append(v);
    }
    if (!changed) return .{ .object = o };
    if (blocks.items.len == 0) return null;
    return try withField(a, o, "content", .{ .array = blocks });
}

/// Something a later request can use: text or a call. Reasoning, thinking or
/// an empty shell left behind by dropped calls is not.
fn substantive(content: ?Value, calls: ?Value) bool {
    if (calls) |c| if (c == .array and c.array.items.len > 0) return true;
    const v = content orelse return false;
    if (v == .string) return v.string.len > 0;
    if (v != .array) return false;
    for (v.array.items) |block| {
        if (block != .object) continue;
        const t = str(block.object, "type") orelse continue;
        if (eql(t, "tool_use")) return true;
        if (!eql(t, "text")) continue;
        const text: []const u8 = str(block.object, "text") orelse "";
        if (text.len > 0) return true;
    }
    return false;
}

fn dropCalls(a: Allocator, o: ObjectMap, d: *const Decisions) !?Value {
    var calls = o.get("tool_calls");
    var calls_changed = false;
    if (calls) |c| if (c == .array) {
        var kept = std.json.Array.init(a);
        for (c.array.items) |call| {
            const id = if (call == .object) str(call.object, "id") else null;
            if (act(d, id) == .drop_call) calls_changed = true else try kept.append(call);
        }
        if (calls_changed) calls = .{ .array = kept };
    };
    var content = o.get("content");
    var content_changed = false;
    if (content) |c| if (c == .array) {
        var kept = std.json.Array.init(a);
        for (c.array.items) |block| {
            const dropped = block == .object and eql(str(block.object, "type") orelse "", "tool_use") and
                act(d, str(block.object, "id")) == .drop_call;
            if (dropped) content_changed = true else try kept.append(block);
        }
        if (content_changed) content = .{ .array = kept };
    };
    if (!calls_changed and !content_changed) return .{ .object = o };
    if (!substantive(content, calls)) return null;
    var c = try cloneObject(a, o);
    if (calls_changed) {
        // An empty tool_calls array is rejected outright; the key goes.
        if (calls.?.array.items.len == 0) _ = c.orderedRemove("tool_calls") else try c.put(a, "tool_calls", calls.?);
    }
    if (content_changed) try c.put(a, "content", content.?);
    return .{ .object = c };
}

/// One native item after the decisions. `removable`: the item is from an
/// earlier turn, so a dropped call goes with its result and stale reasoning
/// goes too (#174). In the live turn a dropped call only loses its result's
/// bulk: that turn's reasoning, thinking and signatures stay paired with every
/// call they reference.
pub fn applyItem(a: Allocator, item: Value, d: *const Decisions, removable: bool, stubber: anytype) !?Value {
    if (item != .object) return item;
    const o = item.object;
    if (str(o, "type")) |t| {
        if (eql(t, "function_call") or eql(t, "custom_tool_call"))
            return if (removable and act(d, str(o, "call_id") orelse str(o, "id")) == .drop_call) null else item;
        if (eql(t, "function_call_output") or eql(t, "custom_tool_call_output"))
            return shrink(a, o, "output", act(d, str(o, "call_id")), removable, .string, stubber);
        if (eql(t, "function_result"))
            return shrink(a, o, "result", act(d, str(o, "call_id")), removable, .parts, stubber);
        if (eql(t, "reasoning") and removable) return null;
        return item;
    }
    const role = str(o, "role") orelse return item;
    if (eql(role, "tool")) return shrink(a, o, "content", act(d, str(o, "tool_call_id")), removable, .string, stubber);
    if (eql(role, "assistant")) return if (removable) dropCalls(a, o, d) else item;
    if (eql(role, "user")) return shrinkBlocks(a, o, d, removable, stubber);
    return item;
}

/// The history to install. `removable_before`: items before this index belong
/// to earlier turns (see applyItem).
pub fn apply(a: Allocator, items: []const Value, msgs: []const Msg, p: Plan, d: *const Decisions, removable_before: usize, note: ?Value, stubber: anytype) !std.json.Array {
    var fresh = std.json.Array.init(a);
    try fresh.ensureTotalCapacity(items.len + 1);
    for (msgs, 0..) |m, j| {
        if (p.note_before == j) if (note) |n| try fresh.append(n);
        if (!p.keep[j]) continue;
        for (items[m.lo..m.hi], m.lo..) |item, i| {
            if (try applyItem(a, item, d, i < removable_before, stubber)) |v| try fresh.append(v);
        }
    }
    return fresh;
}

/// The items a summary replaced (#409 reads their artifact paths).
pub fn replaced(a: Allocator, items: []const Value, msgs: []const Msg, p: Plan) ![]const Value {
    var out: std.ArrayList(Value) = .empty;
    for (msgs, p.keep) |m, k| if (!k) try out.appendSlice(a, items[m.lo..m.hi]);
    return out.items;
}

const IdSet = std.StringHashMapUnmanaged(void);

/// Results without an earlier call, and calls without a later result.
fn unpaired(a: Allocator, items: []const Value) !IdSet {
    const msgs = try fold(a, items, true);
    var calls: IdSet = .empty;
    var answered: IdSet = .empty;
    var bad: IdSet = .empty;
    for (msgs) |m| {
        for (m.uses) |u| try calls.put(a, u.id, {});
        for (m.results) |r| {
            if (!calls.contains(r.id)) try bad.put(a, r.id, {});
            try answered.put(a, r.id, {});
        }
    }
    var it = calls.keyIterator();
    while (it.next()) |id| if (!answered.contains(id.*)) try bad.put(a, id.*, {});
    return bad;
}

/// Refuse a history that pairs worse than the one it replaces: a provider
/// rejects an orphaned result or an unanswered call on every request.
pub fn checkPairs(a: Allocator, before: []const Value, after: []const Value) !void {
    const was = try unpaired(a, before);
    const now = try unpaired(a, after);
    var it = now.keyIterator();
    while (it.next()) |id| if (!was.contains(id.*)) return error.UnpairedToolCall;
}