Skip to content

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

Python
8.0 KB
Raw Blame
//! Server-to-client MCP notifications that arrive while graff waits for a
//! reply: on a stdio pipe between response lines, or as extra events in a
//! Streamable HTTP SSE response. Before this they were read and dropped.
//!
//! - `notifications/tools/list_changed` marks the server's catalog stale;
//!   `mcp_pages.refreshStale` re-lists it before the next model request.
//! - `notifications/progress` for a call graff tagged with a progress token
//!   becomes a transient progress line, like a long shell job's pulse.
//! - An SSE `id:` field is remembered so a stream that drops before the
//!   reply can be resumed with `Last-Event-ID` (mcp_http.resume).

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

pub const Sink = struct {
    server: []const u8 = "",
    tools_stale: std.atomic.Value(bool) = .init(false),
    last_event_id: [128]u8 = undefined,
    last_event_len: u8 = 0,

    pub fn noteEventId(self: *Sink, id: []const u8) void {
        const n: u8 = @intCast(@min(id.len, self.last_event_id.len));
        @memcpy(self.last_event_id[0..n], id[0..n]);
        self.last_event_len = n;
    }

    pub fn lastEventId(self: *const Sink) ?[]const u8 {
        return if (self.last_event_len == 0) null else self.last_event_id[0..self.last_event_len];
    }

    pub fn clearEventId(self: *Sink) void {
        self.last_event_len = 0;
    }
};

/// Where progress lines go: a transient notice like a shell job's pulse.
/// Null drops them.
pub var on_progress: ?*const fn (io: Io, server: []const u8, text: []const u8) void = pulse;

fn pulse(io: Io, server: []const u8, text: []const u8) void {
    @import("tool_pulse.zig").emitNotice(io, "· mcp:{s} · {s}", .{ server, text });
}

pub const Kind = enum { none, tools_changed, progress };

/// Inspect one JSON-RPC message that is not the awaited reply. Returns what
/// it was so callers and tests can tell.
pub fn observe(sink: *Sink, io: Io, bytes: []const u8) Kind {
    var buf: [16 * 1024]u8 = undefined;
    var fba = std.heap.FixedBufferAllocator.init(&buf);
    const trimmed = std.mem.trim(u8, bytes, " \t\r\n");
    if (trimmed.len == 0 or trimmed.len > 8 * 1024) return .none;
    const v = std.json.parseFromSliceLeaky(Value, fba.allocator(), trimmed, .{}) catch return .none;
    if (v != .object) return .none;
    const method = v.object.get("method") orelse return .none;
    if (method != .string or v.object.get("id") != null) return .none; // requests are answered elsewhere
    if (std.mem.eql(u8, method.string, "notifications/tools/list_changed")) {
        sink.tools_stale.store(true, .release);
        return .tools_changed;
    }
    if (std.mem.eql(u8, method.string, "notifications/progress")) {
        const params = v.object.get("params") orelse return .progress;
        if (params != .object) return .progress;
        var line: [256]u8 = undefined;
        const text = progressText(&line, params.object);
        if (on_progress) |emit| if (text.len > 0) emit(io, sink.server, text);
        return .progress;
    }
    return .none;
}

fn number(v: ?Value) ?f64 {
    const x = v orelse return null;
    return switch (x) {
        .integer => |i| @floatFromInt(i),
        .float => |f| f,
        else => null,
    };
}

/// `3/10 indexing files`, `3 indexing files`, or `3/10`.
pub fn progressText(buf: []u8, params: std.json.ObjectMap) []const u8 {
    const done = number(params.get("progress")) orelse return "";
    const message = if (params.get("message")) |m| (if (m == .string) m.string else "") else "";
    const msg = message[0..@min(message.len, 160)];
    if (number(params.get("total"))) |total|
        return std.fmt.bufPrint(buf, "{d}/{d}{s}{s}", .{ done, total, if (msg.len > 0) " " else "", msg }) catch "";
    return std.fmt.bufPrint(buf, "{d}{s}{s}", .{ done, if (msg.len > 0) " " else "", msg }) catch "";
}

/// Tag a built JSON-RPC request line with `_meta.progressToken` = its id so
/// the server may report progress. Only for `tools/call`; every other request
/// keeps its exact bytes.
pub fn withProgressToken(a: Allocator, line: []const u8, id: i64) ![]const u8 {
    const key = "\"params\":{";
    const at = std.mem.indexOf(u8, line, key) orelse return line;
    const after = at + key.len;
    const rest = line[after..];
    if (std.mem.startsWith(u8, rest, "\"_meta\":{")) {
        const meta_rest = rest["\"_meta\":{".len..];
        const meta_sep: []const u8 = if (std.mem.startsWith(u8, meta_rest, "}")) "" else ",";
        return std.fmt.allocPrint(a, "{s}\"_meta\":{{\"progressToken\":{d}{s}{s}", .{ line[0..after], id, meta_sep, meta_rest });
    }
    const sep: []const u8 = if (std.mem.startsWith(u8, rest, "}")) "" else ",";
    return std.fmt.allocPrint(a, "{s}\"_meta\":{{\"progressToken\":{d}}}{s}{s}", .{ line[0..after], id, sep, rest });
}

/// `notifications/cancelled` for request `id` (one line, no trailing newline).
pub fn cancelledLine(a: Allocator, id: i64) ![]const u8 {
    return std.fmt.allocPrint(a,
        \\{{"jsonrpc":"2.0","method":"notifications/cancelled","params":{{"requestId":{d},"reason":"cancelled by the user"}}}}
    , .{id});
}

const testing = std.testing;

test "observe marks the catalog stale and reports progress" {
    var sink: Sink = .{ .server = "demo" };
    try testing.expectEqual(Kind.tools_changed, observe(&sink, testing.io,
        \\{"jsonrpc":"2.0","method":"notifications/tools/list_changed","params":{}}
    ));
    try testing.expect(sink.tools_stale.load(.acquire));
    try testing.expectEqual(Kind.progress, observe(&sink, testing.io,
        \\{"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":4,"progress":3,"total":10,"message":"indexing"}}
    ));
    try testing.expectEqual(Kind.none, observe(&sink, testing.io,
        \\{"jsonrpc":"2.0","id":9,"method":"roots/list"}
    ));
    try testing.expectEqual(Kind.none, observe(&sink, testing.io, "not json"));
}

test "progressText formats with and without a total" {
    var buf: [256]u8 = undefined;
    var arena = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const p1 = try std.json.parseFromSliceLeaky(Value, a, "{\"progress\":3,\"total\":10,\"message\":\"indexing\"}", .{});
    try testing.expectEqualStrings("3/10 indexing", progressText(&buf, p1.object));
    const p2 = try std.json.parseFromSliceLeaky(Value, a, "{\"progress\":7}", .{});
    try testing.expectEqualStrings("7", progressText(&buf, p2.object));
}

test "withProgressToken merges into an existing _meta or adds one" {
    var arena = std.heap.ArenaAllocator.init(testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const legacy = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"t\",\"arguments\":{}}}", 5);
    const lv = try std.json.parseFromSliceLeaky(Value, a, legacy, .{});
    try testing.expectEqual(@as(i64, 5), lv.object.get("params").?.object.get("_meta").?.object.get("progressToken").?.integer);
    try testing.expectEqualStrings("t", lv.object.get("params").?.object.get("name").?.string);
    const modern = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\"},\"name\":\"t\"}}", 6);
    const mv = try std.json.parseFromSliceLeaky(Value, a, modern, .{});
    const meta = mv.object.get("params").?.object.get("_meta").?.object;
    try testing.expectEqual(@as(i64, 6), meta.get("progressToken").?.integer);
    try testing.expect(meta.get("io.modelcontextprotocol/protocolVersion") != null);
    const empty = try withProgressToken(a, "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{}}", 7);
    _ = try std.json.parseFromSliceLeaky(Value, a, empty, .{});
}

test "sink remembers the last SSE event id" {
    var sink: Sink = .{};
    try testing.expect(sink.lastEventId() == null);
    sink.noteEventId("evt-42");
    try testing.expectEqualStrings("evt-42", sink.lastEventId().?);
    sink.clearEventId();
    try testing.expect(sink.lastEventId() == null);
}