graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! 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;
}