Skip to content

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

Python
10.7 KB
Raw Blame
//! ACP JSON-RPC envelopes: parse, version negotiate, prompt flatten, writers.
//! Split from acp.zig so the agent loop can stream session/update without
//! growing that file past 600.

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

/// Highest ACP protocol version this agent implements (v1 shapes).
pub const protocol_version: i64 = 1;

pub const err_method_not_found: i32 = -32601;
pub const err_internal: i32 = -32603;
pub const err_auth_required: i32 = -32000;

/// ACP v1 `promptCapabilities` (https://agentclientprotocol.com/protocol/v1/schema).
/// Missing keys default to false; we send the three named fields so a client
/// does not have to guess. `embeddedContext` includes nested resource contents;
/// resource links are baseline ACP support, independent of this capability.
pub const PromptCapabilities = struct {
    image: bool = false,
    audio: bool = false,
    embeddedContext: bool = true,
};

/// `agentCapabilities.sessionCapabilities`: `{"fork":{}}` when the live CLI can
/// branch a session (acp_session_fork.zig), `{}` for an embed without saves.
pub const SessionCapabilities = struct {
    fork: bool = false,

    pub fn jsonStringify(self: @This(), s: anytype) !void {
        try s.beginObject();
        if (self.fork) {
            try s.objectField("fork");
            try s.write(struct {}{});
        }
        try s.endObject();
    }
};

pub const AgentImplementation = struct {
    name: []const u8 = "graff",
    title: []const u8 = "graff",
    version: []const u8,
};

pub const AvailableCommand = struct {
    name: []const u8,
    description: []const u8,
    input: struct { hint: []const u8 },
};

pub const Request = struct {
    id: ?Value = null,
    method: []const u8 = "",
    params: ?Value = null,
};

pub fn parseRequest(arena: Allocator, line: []const u8) ?Request {
    const trimmed = std.mem.trim(u8, line, " \t\r\n");
    if (trimmed.len == 0) return null;
    const v = std.json.parseFromSliceLeaky(Value, arena, trimmed, .{ .allocate = .alloc_always }) catch return null;
    if (v != .object) return null;
    const method = util.strFieldObj(v.object, "method") orelse return null;
    const raw_id = v.object.get("id");
    return .{
        .id = if (raw_id) |id| (if (id == .null) null else id) else null,
        .method = method,
        .params = v.object.get("params"),
    };
}

pub fn negotiateVersion(params: ?Value) i64 {
    // ACP requires the requested version if supported, otherwise our latest.
    // v2 is supported only behind GRAFF_ACP_V2=1 (acp_v2.zig); never echo 0.
    return @import("acp_v2.zig").negotiated(params);
}

fn blockText(block: Value) ?[]const u8 {
    if (block == .string) return block.string;
    if (block != .object) return null;
    const o = block.object;
    const kind = util.strFieldObj(o, "type") orelse "";
    if (std.mem.eql(u8, kind, "text")) return util.strFieldObj(o, "text");
    if (std.mem.eql(u8, kind, "resource_link"))
        return util.strFieldObj(o, "uri") orelse util.strFieldObj(o, "name");
    // Media blocks are the pixels/samples themselves (staged by acp_images);
    // their optional `uri` is provenance, not words the user typed.
    if (std.mem.eql(u8, kind, "image") or std.mem.eql(u8, kind, "audio")) return null;
    return util.strFieldObj(o, "text") orelse util.strFieldObj(o, "uri");
}

pub fn flattenPrompt(arena: Allocator, prompt: ?Value) ![]const u8 {
    const blocks = switch (prompt orelse return "") {
        .array => |a| a,
        .string => |s| return s,
        else => return "",
    };
    var buf: std.array_list.Managed(u8) = .init(arena);
    for (blocks.items) |block| {
        if (block == .object and std.mem.eql(u8, util.strFieldObj(block.object, "type") orelse "", "resource")) {
            const resource = block.object.get("resource") orelse continue;
            if (resource != .object) continue;
            const o = resource.object;
            const text = util.strFieldObj(o, "text");
            const blob = util.strFieldObj(o, "blob");
            if (text == null and blob == null) continue;
            if (buf.items.len != 0) try buf.append('\n');
            if (util.strFieldObj(o, "uri")) |uri| {
                try buf.appendSlice(uri);
                try buf.append('\n');
            }
            if (text) |content| {
                try buf.appendSlice(content);
            } else if (blob) |content| {
                // Preserve opaque bytes in their wire encoding, never as UTF-8.
                try buf.appendSlice("[base64");
                if (util.strFieldObj(o, "mimeType")) |mime| {
                    try buf.appendSlice(" ");
                    try buf.appendSlice(mime);
                }
                try buf.appendSlice("]\n");
                try buf.appendSlice(content);
            }
            continue;
        }
        const text = blockText(block) orelse continue;
        if (text.len == 0) continue;
        if (buf.items.len != 0) try buf.append('\n');
        try buf.appendSlice(text);
    }
    return buf.items;
}

test "flattenPrompt: an image block's uri never becomes prompt text" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const prompt = try std.json.parseFromSliceLeaky(Value, a,
        \\[{"type":"text","text":"what colour is it"},
        \\ {"type":"image","data":"iVBORw0KGgo=","mimeType":"image/png","uri":"file:///tmp/shot.png"},
        \\ {"type":"audio","data":"AAAA","mimeType":"audio/wav","uri":"file:///tmp/a.wav"}]
    , .{});
    try std.testing.expectEqualStrings("what colour is it", try flattenPrompt(a, prompt));
}

test "ACP v1 rejects unsupported version claims without numeric conversion" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    for ([_][]const u8{ "0", "-1", "2", "1.5", "1e100" }) |version| {
        const json = try std.fmt.allocPrint(arena.allocator(), "{{\"protocolVersion\":{s}}}", .{version});
        const value = try std.json.parseFromSliceLeaky(Value, arena.allocator(), json, .{});
        try std.testing.expectEqual(protocol_version, negotiateVersion(value));
    }
}

test "ACP embedded resources preserve URI and text alongside prompt blocks" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const value = try std.json.parseFromSliceLeaky(Value, a,
        \\[{"type":"text","text":"Review this"},{"type":"resource","resource":{"uri":"file:///draft.zig","mimeType":"text/plain","text":"const draft = 1;\n"}},{"type":"resource_link","uri":"file:///related.zig"}]
    , .{});
    try std.testing.expectEqualStrings("Review this\nfile:///draft.zig\nconst draft = 1;\n\nfile:///related.zig", try flattenPrompt(a, value));
}

test "ACP embedded blobs retain encoding and malformed resources are skipped" {
    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
    defer arena.deinit();
    const a = arena.allocator();
    const value = try std.json.parseFromSliceLeaky(Value, a,
        \\[{"type":"resource"},{"type":"resource","resource":4},{"type":"resource","resource":{"text":3}},{"type":"resource","resource":{"uri":"memory://bytes","mimeType":"application/octet-stream","blob":"AAEC"}}]
    , .{});
    try std.testing.expectEqualStrings("memory://bytes\n[base64 application/octet-stream]\nAAEC", try flattenPrompt(a, value));
}

pub fn writeResult(w: *Io.Writer, id: ?Value, result: anytype) !void {
    var s: std.json.Stringify = .{ .writer = w };
    try s.beginObject();
    try s.objectField("jsonrpc");
    try s.write("2.0");
    try s.objectField("id");
    try s.write(id);
    try s.objectField("result");
    try s.write(result);
    try s.endObject();
    try w.writeByte('\n');
}

pub fn writeError(w: *Io.Writer, id: ?Value, code: i32, message: []const u8) !void {
    return writeErrorData(w, id, code, message, null);
}

pub fn writeErrorData(w: *Io.Writer, id: ?Value, code: i32, message: []const u8, data: anytype) !void {
    var s: std.json.Stringify = .{ .writer = w };
    try s.beginObject();
    try s.objectField("jsonrpc");
    try s.write("2.0");
    try s.objectField("id");
    try s.write(id);
    try s.objectField("error");
    try s.beginObject();
    try s.objectField("code");
    try s.write(code);
    try s.objectField("message");
    try s.write(message);
    if (@TypeOf(data) != @TypeOf(null)) {
        try s.objectField("data");
        try s.write(data);
    }
    try s.endObject();
    try s.endObject();
    try w.writeByte('\n');
}

pub fn writeNotification(w: *Io.Writer, method: []const u8, params: anytype) !void {
    var s: std.json.Stringify = .{ .writer = w };
    try s.write(.{ .jsonrpc = "2.0", .method = method, .params = params });
    try w.writeByte('\n');
}

/// One `agent_message_chunk` notification (the v0 final-text update).
/// Provider citation markers are removed on the way out (acp_citations.zig).
pub fn writeSessionUpdate(w: *Io.Writer, session_id: []const u8, raw: []const u8) !void {
    const cleaned = @import("acp_citations.zig").filter(session_id, .message, raw);
    defer cleaned.deinit();
    const text = cleaned.text;
    if (text.len == 0 and raw.len != 0) return; // the chunk was all marker
    const v2 = @import("acp_v2.zig");
    if (v2.on()) return v2.writeChunk(w, session_id, false, text);
    try writeNotification(w, "session/update", .{
        .sessionId = session_id,
        .update = .{
            .sessionUpdate = "agent_message_chunk",
            .content = .{ .type = "text", .text = text },
        },
    });
}

/// ACP v1 slash-command advertisement (`available_commands_update`).
pub fn writeAvailableCommands(w: *Io.Writer, session_id: []const u8, commands: []const AvailableCommand) !void {
    try writeNotification(w, "session/update", .{
        .sessionId = session_id,
        .update = .{
            .sessionUpdate = "available_commands_update",
            .availableCommands = commands,
        },
    });
}

/// The advertised set, built from the one catalog the REPL and tab
/// completion already read, so a command cannot exist in one surface and be
/// missing from the other. Names go out bare: ACP owns the leading slash.
pub fn slashCommands() []const AvailableCommand {
    const built = comptime blk: {
        var out: [command_catalog.commands.len]AvailableCommand = undefined;
        var n: usize = 0;
        for (command_catalog.commands) |c| {
            out[n] = .{
                .name = c.name[1..],
                .description = c.desc,
                .input = .{ .hint = c.usage },
            };
            n += 1;
        }
        const frozen = out[0..n].*;
        break :blk frozen;
    };
    return &built;
}