graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! ACP v2 (draft) wire shapes. Negotiated per process at `initialize` when
//! the client asks for protocolVersion >= 2 AND `GRAFF_ACP_V2=1`; every other
//! connection keeps the v1 shapes byte-for-byte (ADR 0206). One ACP
//! connection per process, so the negotiated state is a process global.
const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const acp_auth = @import("acp_auth.zig");
pub const version: i64 = 2;
var active = std.atomic.Value(bool).init(false);
/// Tests pin the gate; null reads `GRAFF_ACP_V2`.
pub var gate: ?bool = null;
pub fn on() bool {
return active.load(.acquire);
}
pub fn gateOpen() bool {
if (gate) |g| return g;
const v = std.c.getenv("GRAFF_ACP_V2") orelse return false;
return std.mem.eql(u8, std.mem.span(v), "1");
}
fn requested(params: ?Value) i64 {
const p = params orelse return 1;
if (p != .object) return 1;
const v = p.object.get("protocolVersion") orelse return 1;
return if (v == .integer) v.integer else 1;
}
/// The version to answer with. ACP: the requested one when supported, else
/// our latest — v2 is only "supported" behind the gate.
pub fn negotiated(params: ?Value) i64 {
return if (gateOpen() and requested(params) >= version) version else 1;
}
/// Latch the connection's wire at `initialize` (a re-initialize may downgrade).
pub fn negotiate(params: ?Value, seed: u64) void {
const v2 = negotiated(params) == version;
if (v2) prefix = seed;
kind = .none;
active.store(v2, .release);
}
// ── message IDs ─────────────────────────────────────────────────────────
// A message is one contiguous run of agent text or thought. Switching kind or
// reporting a tool starts a new ID, so later text never appends above a tool
// row that the client already rendered. Callers hold the ACP output lock.
const Kind = enum { none, agent, thought };
var prefix: u64 = 0;
var counter = std.atomic.Value(u64).init(0);
var kind: Kind = .none;
var current: [48]u8 = undefined;
var current_len: usize = 0;
pub fn mint(buf: *[48]u8, role: []const u8) []const u8 {
const n = counter.fetchAdd(1, .monotonic) + 1;
return std.fmt.bufPrint(buf, "msg_{s}_{x}_{d}", .{ role, prefix, n }) catch "msg";
}
fn messageId(k: Kind) []const u8 {
if (kind != k or current_len == 0) {
current_len = mint(¤t, @tagName(k)).len;
kind = k;
}
return current[0..current_len];
}
/// A tool event or turn boundary ends the current message.
pub fn breakMessage() void {
kind = .none;
}
pub fn writeChunk(w: *Io.Writer, sid: []const u8, thought: bool, text: []const u8) !void {
const id = messageId(if (thought) .thought else .agent);
try notify(w, sid, .{
.sessionUpdate = if (thought) "agent_thought_chunk" else "agent_message_chunk",
.messageId = id,
.content = .{ .type = "text", .text = text },
});
}
pub fn writeUserMessage(w: *Io.Writer, sid: []const u8, id: []const u8, prompt: ?Value, text: []const u8) !void {
breakMessage();
if (prompt) |p| if (p == .array) return notify(w, sid, .{ .sessionUpdate = "user_message", .messageId = id, .content = p });
try notify(w, sid, .{ .sessionUpdate = "user_message", .messageId = id, .content = .{.{ .type = "text", .text = text }} });
}
pub fn writeRunning(w: *Io.Writer, sid: []const u8) !void {
try notify(w, sid, .{ .sessionUpdate = "state_update", .state = "running" });
}
pub fn writeRequiresAction(w: *Io.Writer, sid: []const u8) !void {
try notify(w, sid, .{ .sessionUpdate = "state_update", .state = "requires_action" });
}
pub fn writeIdle(w: *Io.Writer, sid: []const u8, stop: []const u8) !void {
breakMessage();
try notify(w, sid, .{ .sessionUpdate = "state_update", .state = "idle", .stopReason = stop });
}
/// A turn that failed after its prompt was accepted: the JSON-RPC request is
/// already answered, so the error rides the idle transition (custom `_` reason).
pub fn writeFailed(w: *Io.Writer, sid: []const u8, message: []const u8) !void {
breakMessage();
try notify(w, sid, .{
.sessionUpdate = "state_update",
.state = "idle",
.stopReason = "_error",
._meta = .{ .@"graff/error" = message },
});
}
pub fn writeFailedRecovery(w: *Io.Writer, sid: []const u8, message: []const u8, recovery: ?@import("auth_recovery.zig").Recovery) !void {
const data = recovery orelse return writeFailed(w, sid, message);
breakMessage();
// ADR 0310: only a sign-in action rides `graff/reauth`, which clients read
// as "signed out"; a rejected API key rides `graff/recovery`.
if (data.login == null) return notify(w, sid, .{
.sessionUpdate = "state_update",
.state = "idle",
.stopReason = "_error",
._meta = .{ .@"graff/error" = message, .@"graff/recovery" = data },
});
try notify(w, sid, .{
.sessionUpdate = "state_update",
.state = "idle",
.stopReason = "_error",
._meta = .{ .@"graff/error" = message, .@"graff/reauth" = data },
});
}
pub fn writeUsage(w: *Io.Writer, sid: []const u8, used: u64, size: u64) !void {
try notify(w, sid, .{ .sessionUpdate = "usage_update", .used = used, .size = size });
}
fn notify(w: *Io.Writer, sid: []const u8, update: anytype) !void {
var s: std.json.Stringify = .{ .writer = w };
try s.write(.{ .jsonrpc = "2.0", .method = "session/update", .params = .{ .sessionId = sid, .update = update } });
try w.writeByte('\n');
}
// ── initialize ──────────────────────────────────────────────────────────
pub const Info = struct {
name: []const u8 = "graff",
title: []const u8 = "graff",
version: []const u8,
};
const Empty = struct {};
/// v2 `initialize` result: `info` + object-marker `capabilities` (an absent
/// capability is omitted, never `false`/`null`). Graff extensions ride `_meta`.
pub fn initializeResult(params: ?Value, can_load: bool, impl_version: []const u8) InitializeResult {
return .{ .can_load = can_load, .terminal_auth = clientTerminalAuth(params), .info = .{ .version = impl_version } };
}
/// v2 renames the method key to `methodId`, and a `terminal` method may be
/// advertised only to a client that sent `capabilities.auth.terminal`.
const TerminalAuth = struct {
methodId: []const u8,
name: []const u8,
description: []const u8,
type: []const u8 = "terminal",
args: []const []const u8,
};
const terminal_login = blk: {
var methods: [acp_auth.advertised.len]TerminalAuth = undefined;
for (acp_auth.advertised, 0..) |method, i| methods[i] = .{
.methodId = method.id,
.name = method.name,
.description = method.description,
.args = method.args,
};
break :blk methods;
};
fn clientTerminalAuth(params: ?Value) bool {
const p = params orelse return false;
if (p != .object) return false;
const caps = p.object.get("capabilities") orelse return false;
if (caps != .object) return false;
const auth = caps.object.get("auth") orelse return false;
if (auth != .object) return false;
const terminal = auth.object.get("terminal") orelse return false;
return terminal == .object;
}
const InitializeResult = struct {
can_load: bool,
terminal_auth: bool,
info: Info,
pub fn jsonStringify(self: @This(), s: anytype) !void {
try s.beginObject();
try s.objectField("protocolVersion");
try s.write(version);
try s.objectField("capabilities");
try s.beginObject();
try s.objectField("session");
try s.beginObject();
try s.objectField("prompt");
try s.beginObject();
if (self.can_load) {
try s.objectField("image");
try s.write(Empty{});
}
try s.objectField("embeddedContext");
try s.write(Empty{});
try s.endObject();
try s.objectField("mcp");
try s.write(.{ .stdio = Empty{}, .http = Empty{} });
if (self.can_load) {
try s.objectField("fork");
try s.write(Empty{});
}
try s.endObject();
try s.objectField("_meta");
try s.write(.{ .@"codegraff/usage" = self.can_load, .@"graff/backgroundSubagents" = true });
try s.endObject();
try s.objectField("info");
try s.write(self.info);
try s.objectField("authMethods");
try s.write(if (self.terminal_auth) terminal_login[0..] else terminal_login[0..0]);
try s.endObject();
}
};
pub fn resetForTest() void {
active.store(false, .release);
gate = null;
kind = .none;
}
test "v2 needs both the client's request and the GRAFF_ACP_V2 gate" {
defer resetForTest();
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();
const two = try std.json.parseFromSliceLeaky(Value, arena.allocator(), "{\"protocolVersion\":2}", .{});
const one = try std.json.parseFromSliceLeaky(Value, arena.allocator(), "{\"protocolVersion\":1}", .{});
const nine = try std.json.parseFromSliceLeaky(Value, arena.allocator(), "{\"protocolVersion\":9}", .{});
gate = false;
try std.testing.expectEqual(@as(i64, 1), negotiated(two));
gate = true;
try std.testing.expectEqual(@as(i64, 2), negotiated(two));
try std.testing.expectEqual(@as(i64, 2), negotiated(nine));
try std.testing.expectEqual(@as(i64, 1), negotiated(one));
try std.testing.expectEqual(@as(i64, 1), negotiated(null));
negotiate(two, 7);
try std.testing.expect(on());
negotiate(one, 7);
try std.testing.expect(!on());
}
test "message IDs change with the message kind and after a tool" {
defer resetForTest();
var buf: [2048]u8 = undefined;
var w: Io.Writer = .fixed(&buf);
try writeChunk(&w, "s", false, "a");
try writeChunk(&w, "s", false, "b");
const first = current[0..current_len];
var keep: [48]u8 = undefined;
@memcpy(keep[0..first.len], first);
try writeChunk(&w, "s", true, "think");
try std.testing.expect(!std.mem.eql(u8, keep[0..first.len], current[0..current_len]));
breakMessage();
try writeChunk(&w, "s", false, "c");
const out = w.buffered();
try std.testing.expectEqual(@as(usize, 4), std.mem.count(u8, out, "\"messageId\":"));
try std.testing.expectEqual(@as(usize, 2), std.mem.count(u8, out, keep[0..first.len]));
}
test "v2 initialize uses info and object-marker capabilities" {
var buf: [1024]u8 = undefined;
var w: Io.Writer = .fixed(&buf);
var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena.deinit();
try std.json.Stringify.value(initializeResult(null, false, "t"), .{}, &w);
var out = w.buffered();
try std.testing.expect(std.mem.startsWith(u8, out, "{\"protocolVersion\":2,\"capabilities\":{\"session\":{\"prompt\":{\"embeddedContext\":{}},\"mcp\":{\"stdio\":{},\"http\":{}}}"));
try std.testing.expect(std.mem.indexOf(u8, out, "\"info\":{\"name\":\"graff\"") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "agentCapabilities") == null);
try std.testing.expect(std.mem.indexOf(u8, out, "null") == null);
try std.testing.expect(std.mem.endsWith(u8, out, "\"authMethods\":[]}"));
const params = try std.json.parseFromSliceLeaky(Value, arena.allocator(), "{\"capabilities\":{\"auth\":{\"terminal\":{}}}}", .{});
w = .fixed(&buf);
try std.json.Stringify.value(initializeResult(params, true, "t"), .{}, &w);
out = w.buffered();
try std.testing.expect(std.mem.indexOf(u8, out, "\"image\":{}") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "\"methodId\":\"graff-login\"") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "\"methodId\":\"graff-login-anthropic\"") != null);
try std.testing.expect(std.mem.indexOf(u8, out, "\"args\":[\"login\",\"anthropic\"]") != null);
}