graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Z.AI GLM chat extras on the OpenAI-compatible wire.
//!
//! GLM-5.3 always reasons: `thinking.type` is only `enabled` (disabled fails)
//! and `reasoning_effort` is `low` | `high` | `max` (docs default `max`).
//! Graff's default is `medium`, which the API rejects — map it here.
//!
//! Context cache is implicit on identical prefixes
//! (`usage.prompt_tokens_details.cached_tokens`). Preserved thinking
//! (`clear_thinking: false`) keeps replayed `reasoning_content` in that
//! prefix so a tool turn does not drop the hit (docs.z.ai thinking-mode).
const std = @import("std");
/// Map a graff `/effort` tag onto Z.AI's allow-list. `medium` → `high`
/// (closest middle rung); `xhigh` / `ultra` → `max`.
pub fn reasoningEffort(requested: []const u8) []const u8 {
if (std.mem.eql(u8, requested, "low")) return "low";
if (std.mem.eql(u8, requested, "high")) return "high";
if (std.mem.eql(u8, requested, "max")) return "max";
if (std.mem.eql(u8, requested, "xhigh") or std.mem.eql(u8, requested, "ultra")) return "max";
return "high";
}
/// Vercel AI Gateway Chat Completions uses `reasoning.effort`
/// (none|minimal|low|medium|high|xhigh), not top-level reasoning_effort.
/// Graff `max`/`ultra` → `xhigh`.
pub fn vercelEffort(requested: []const u8) []const u8 {
if (std.mem.eql(u8, requested, "low")) return "low";
if (std.mem.eql(u8, requested, "medium")) return "medium";
if (std.mem.eql(u8, requested, "high")) return "high";
if (std.mem.eql(u8, requested, "xhigh")) return "xhigh";
if (std.mem.eql(u8, requested, "max") or std.mem.eql(u8, requested, "ultra")) return "xhigh";
return "medium";
}
/// DeepSeek V4 (native or via codegraff/fireworks): thinking is ON at
/// high unless `thinking.type` is `disabled`. `reasoning_effort: low`
/// still emits `reasoning_content` (ADR 0054).
pub fn isDeepseekFamily(provider_id: []const u8, model: []const u8) bool {
if (std.mem.eql(u8, provider_id, "deepseek")) return true;
return std.mem.indexOf(u8, model, "deepseek") != null;
}
/// ADR 0237: DeepSeek documents `low`, `high` and `max`. At graff's default
/// (`medium`) the first request of an MCP task planned the whole job before
/// its first call. The default keeps thinking on at `low`; `/effort low`
/// still turns it off (writeChatExtras).
pub fn deepseekEffort(requested: []const u8) []const u8 {
return if (std.mem.eql(u8, requested, "medium")) "low" else requested;
}
/// OpenAI-chat extras after `prompt_cache_key`: Z.AI thinking, Vercel
/// `reasoning.effort`, DeepSeek thinking on/off, then `reasoning_effort`.
pub fn writeChatExtras(s: *std.json.Stringify, provider_id: []const u8, model: []const u8, send_effort: bool, requested: []const u8) !void {
if (@import("effort_route.zig").mimoRoute(provider_id, model)) {
try s.objectField("thinking");
try s.beginObject();
try s.objectField("type");
try s.write(if (std.mem.eql(u8, requested, "none")) "disabled" else "enabled");
try s.endObject();
return;
}
const is_zai = std.mem.eql(u8, provider_id, "zai");
const is_vercel = std.mem.eql(u8, provider_id, "vercel");
if (is_zai) {
try s.objectField("thinking");
try s.print("{s}", .{"{\"type\":\"enabled\",\"clear_thinking\":false}"});
} else if (isDeepseekFamily(provider_id, model) and send_effort) {
// Official off switch. GLM rejects type=disabled; do not send it there.
try s.objectField("thinking");
try s.print("{s}", .{if (std.mem.eql(u8, requested, "low"))
"{\"type\":\"disabled\"}"
else
"{\"type\":\"enabled\"}"});
}
if (is_vercel and send_effort) {
try s.objectField("reasoning");
try s.beginObject();
try s.objectField("effort");
try s.write(vercelEffort(requested));
try s.endObject();
return;
}
if (!std.mem.eql(u8, provider_id, "kimi") and send_effort) {
try s.objectField("reasoning_effort");
const effort = @import("meta_wire.zig").chatEffort(requested, provider_id, model);
try s.write(if (is_zai) reasoningEffort(requested) else if (isDeepseekFamily(provider_id, model)) deepseekEffort(effort) else effort);
}
}
test "DeepSeek family is native id or a deepseek model name" {
try std.testing.expect(isDeepseekFamily("deepseek", "deepseek-v4-pro"));
try std.testing.expect(isDeepseekFamily("codegraff", "deepseek-v4-flash"));
try std.testing.expect(isDeepseekFamily("fireworks", "accounts/fireworks/models/deepseek-v4-flash"));
try std.testing.expect(!isDeepseekFamily("codegraff", "glm-5.3-flash"));
try std.testing.expect(!isDeepseekFamily("zai", "glm-5.3"));
}
test "ADR 0237: DeepSeek thinks at its low level by default; /effort low turns thinking off" {
const Agent = @import("agent.zig").Agent;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
var messages = std.json.Array.init(arena);
var user: std.json.ObjectMap = .empty;
try user.put(arena, "role", .{ .string = "user" });
try user.put(arena, "content", .{ .string = "hello" });
try messages.append(.{ .object = user });
var agent: Agent = .{
.gpa = std.testing.allocator,
.arena = arena,
.io = std.testing.io,
.client = undefined,
.provider = .{ .id = "deepseek", .kind = .openai, .auth = .bearer, .url = "https://api.deepseek.com/chat/completions", .api_key = "k", .model = "deepseek-v4-pro", .context = 1_000_000 },
.messages = messages,
.sub = false,
.label = "",
.out = null,
.sys_normal = "system",
.reasoning = .medium,
};
const cases = [_]struct { effort: @TypeOf(agent.reasoning), thinking: []const u8, wire: []const u8 }{
.{ .effort = .medium, .thinking = "enabled", .wire = "low" }, // graff's default
.{ .effort = .low, .thinking = "disabled", .wire = "low" },
.{ .effort = .high, .thinking = "enabled", .wire = "high" },
.{ .effort = .ultra, .thinking = "enabled", .wire = "max" },
};
for (cases) |c| {
agent.reasoning = c.effort;
const body = try agent.buildBody(null, false, true, true);
defer std.testing.allocator.free(body);
const thinking = try std.fmt.allocPrint(arena, "\"thinking\":{{\"type\":\"{s}\"}}", .{c.thinking});
const wire = try std.fmt.allocPrint(arena, "\"reasoning_effort\":\"{s}\"", .{c.wire});
try std.testing.expect(std.mem.indexOf(u8, body, thinking) != null);
try std.testing.expect(std.mem.indexOf(u8, body, wire) != null);
}
try std.testing.expectEqualStrings("low", deepseekEffort("medium"));
try std.testing.expectEqualStrings("high", deepseekEffort("high"));
}
test "Z.AI maps graff efforts onto low|high|max" {
try std.testing.expectEqualStrings("low", reasoningEffort("low"));
try std.testing.expectEqualStrings("high", reasoningEffort("medium"));
try std.testing.expectEqualStrings("high", reasoningEffort("high"));
try std.testing.expectEqualStrings("max", reasoningEffort("xhigh"));
try std.testing.expectEqualStrings("max", reasoningEffort("max"));
try std.testing.expectEqualStrings("max", reasoningEffort("ultra"));
}
test "Z.AI chat body sends thinking.enabled and remaps medium to high" {
const Agent = @import("agent.zig").Agent;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
var messages = std.json.Array.init(arena);
var user: std.json.ObjectMap = .empty;
try user.put(arena, "role", .{ .string = "user" });
try user.put(arena, "content", .{ .string = "hello" });
try messages.append(.{ .object = user });
var agent: Agent = .{
.gpa = std.testing.allocator,
.arena = arena,
.io = std.testing.io,
.client = undefined,
.provider = .{
.id = "zai",
.kind = .openai,
.auth = .bearer,
.url = "https://api.z.ai/api/paas/v4/chat/completions",
.api_key = "k",
.model = "glm-5.3",
.context = 1_000_000,
},
.messages = messages,
.sub = false,
.label = "",
.out = null,
.sys_normal = "system",
.reasoning = .medium,
};
const body = try agent.buildBody(null, false, true, true);
defer std.testing.allocator.free(body);
try std.testing.expect(std.mem.indexOf(u8, body, "\"thinking\":{\"type\":\"enabled\",\"clear_thinking\":false}") != null);
try std.testing.expect(std.mem.indexOf(u8, body, "\"prompt_cache_key\":\"") != null);
try std.testing.expect(std.mem.indexOf(u8, body, "\"reasoning_effort\":\"high\"") != null);
try std.testing.expect(std.mem.indexOf(u8, body, "\"reasoning_effort\":\"medium\"") == null);
agent.reasoning = .max;
const max_body = try agent.buildBody(null, false, true, true);
defer std.testing.allocator.free(max_body);
try std.testing.expect(std.mem.indexOf(u8, max_body, "\"reasoning_effort\":\"max\"") != null);
}
test "Keys.build: GRAFF_ZAI_URL rewires only the Z.AI endpoint" {
const provider_mod = @import("provider.zig");
const Keys = provider_mod.Keys;
const all = Keys{ .values = @splat("k") };
provider_mod.g_zai_url_override = provider_mod.zai_coding_url;
defer provider_mod.g_zai_url_override = null;
const zai = try all.providerById("zai", "glm-5.3");
try std.testing.expectEqualStrings(provider_mod.zai_coding_url, zai.url);
const deepseek = try all.providerById("deepseek", "deepseek-v4-pro");
try std.testing.expectEqualStrings("https://api.deepseek.com/chat/completions", deepseek.url);
}
test "Vercel maps graff efforts onto reasoning.effort" {
try std.testing.expectEqualStrings("low", vercelEffort("low"));
try std.testing.expectEqualStrings("medium", vercelEffort("medium"));
try std.testing.expectEqualStrings("high", vercelEffort("high"));
try std.testing.expectEqualStrings("xhigh", vercelEffort("xhigh"));
try std.testing.expectEqualStrings("xhigh", vercelEffort("max"));
try std.testing.expectEqualStrings("xhigh", vercelEffort("ultra"));
}
test "Vercel chat body sends reasoning.effort and not reasoning_effort" {
const Agent = @import("agent.zig").Agent;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
var messages = std.json.Array.init(arena);
var user: std.json.ObjectMap = .empty;
try user.put(arena, "role", .{ .string = "user" });
try user.put(arena, "content", .{ .string = "hello" });
try messages.append(.{ .object = user });
var agent: Agent = .{
.gpa = std.testing.allocator,
.arena = arena,
.io = std.testing.io,
.client = undefined,
.provider = .{
.id = "vercel",
.kind = .openai,
.auth = .bearer,
.url = "https://ai-gateway.vercel.sh/coding-agent/v1/chat/completions",
.api_key = "k",
.model = "alibaba/qwen3.8-27b",
.context = 1_000_000,
},
.messages = messages,
.sub = false,
.label = "",
.out = null,
.sys_normal = "system",
.reasoning = .medium,
};
const body = try agent.buildBody(null, false, true, true);
defer std.testing.allocator.free(body);
try std.testing.expect(std.mem.indexOf(u8, body, "\"reasoning\":{\"effort\":\"medium\"}") != null);
try std.testing.expect(std.mem.indexOf(u8, body, "\"reasoning_effort\"") == null);
try std.testing.expect(std.mem.indexOf(u8, body, "\"prompt_cache_key\":\"") != null);
agent.reasoning = .max;
const max_body = try agent.buildBody(null, false, true, true);
defer std.testing.allocator.free(max_body);
try std.testing.expect(std.mem.indexOf(u8, max_body, "\"reasoning\":{\"effort\":\"xhigh\"}") != null);
}