Skip to content

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

Python

Keep one copy of the prompt and subagent tool lists in the binary

Rach Pradhan0e5d355567b3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3020680b..3cf0d222 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ current is part of cutting a release.
- Release binaries are built ReleaseSafe: an out-of-range index or overflow stops graff with a clear panic instead of silently corrupting state, and the stripped binaries are about 17-20% smaller.
- `graff learn` is no longer part of the release binary, which is about 300 KB smaller for it; sessions no longer start background learning trials.
- Release binaries are another 50-120 KB smaller: the MCP installer and two HTML pages ship gzipped, the sign-in page's images are WebP, and graff's own code on Windows drops its unwind tables like the other platforms.
+- Release binaries are about 100 KB smaller again: the system prompt's variants share one copy, subagent tool lists for gated sessions are built when first needed instead of compiled in, and the MCP task page ships gzipped.
- Retains all changes from v0.302.51.
## v0.302.51
diff --git a/build.zig b/build.zig
index 19aefdc1..ca373ec2 100644
--- a/build.zig
+++ b/build.zig
@@ -136,8 +136,6 @@ pub fn build(b: *std.Build) void {
unit_tests.root_module.addImport("slash_suggest", slash_suggest_mod);
// spec/ fixtures live outside src/; importing them here makes @embedFile
// legal and rebuilds the suite when the exported semantics change.
- app_mod.addAnonymousImport("ui_theme", .{ .root_source_file = b.path("src/ui_theme.css") });
- unit_tests.root_module.addAnonymousImport("ui_theme", .{ .root_source_file = b.path("src/ui_theme.css") });
unit_tests.root_module.addAnonymousImport("spec_tool_catalog", .{ .root_source_file = b.path("spec/kernels/tool_catalog.json") });
unit_tests.root_module.addAnonymousImport("spec_transport", .{ .root_source_file = b.path("spec/kernels/transport.json") });
unit_tests.root_module.addAnonymousImport("spec_providers", .{ .root_source_file = b.path("spec/kernels/providers.json") });
@@ -307,6 +305,8 @@ pub fn build(b: *std.Build) void {
.{ .import = "mcp_installer.gz", .path = "scripts/install-mcp.py" },
.{ .import = "chatgpt_callback.gz", .path = "src/oauth_page/chatgpt_callback.html" },
.{ .import = "mcp_app_host.gz", .path = "src/mcp_app_host.html" },
+ .{ .import = "mcp_task_app.gz", .path = "src/mcp_task_app.html" },
+ .{ .import = "ui_theme.gz", .path = "src/ui_theme.css" },
}) |asset| {
const gzip_run = b.addRunArtifact(gzip_asset);
gzip_run.addFileArg(b.path(asset.path));
diff --git a/scripts/eval/tier1-manifest.json b/scripts/eval/tier1-manifest.json
index 5600455f..61d3f491 100644
--- a/scripts/eval/tier1-manifest.json
+++ b/scripts/eval/tier1-manifest.json
@@ -14,7 +14,7 @@
"src/main.zig",
"src/repl.zig"
],
- "test_count_baseline": 3500,
+ "test_count_baseline": 3502,
"test_count_slack": 25,
"required_invariants": [
{
diff --git a/src/agent.zig b/src/agent.zig
index 16335f10..4413b91f 100644
--- a/src/agent.zig
+++ b/src/agent.zig
@@ -185,7 +185,7 @@ pub const Agent = struct {
sys_base: []const u8 = "", // #381: the last BASE handed to prompts.setSystemPrompts, WITHOUT the playbook block — what a mid-session constraint re-composes from (playbook_glue.refreshRoot)
sys_strict: []const u8 = prompts.main_system_prompt_strict,
sys_ultra: []const u8 = prompts.main_system_prompt ++ prompts.ultracode_system_note, // #326: comptime defaults only — prompts.setSystemPrompts() is the sole production writer
- sys_ultra_strict: []const u8 = prompts.main_system_prompt_strict ++ prompts.ultracode_system_note, // composes onto sys_strict, never replaces it
+ sys_ultra_strict: []const u8 = prompts.main_system_prompt_ultra_strict, // composes onto sys_strict, never replaces it
tools_anthropic: []const u8 = schema.tools_anthropic_sub,
tools_openai: []const u8 = schema.tools_openai_sub,
tools_responses: []const u8 = schema.tools_responses_sub,
diff --git a/src/mcp_server.zig b/src/mcp_server.zig
index 857e9cde..0baceae6 100644
--- a/src/mcp_server.zig
+++ b/src/mcp_server.zig
@@ -93,7 +93,7 @@ pub const Server = struct {
if (std.mem.eql(u8, method, "resources/read")) {
const uri = string(params, "uri") orelse return failure(out, id, -32602, "Resource URI is required");
if (!std.mem.eql(u8, uri, app.uri)) return failure(out, id, -32002, "Resource not found");
- return answer.send(app.contents(), true);
+ return answer.send(try app.contents(a), true);
}
if (!std.mem.eql(u8, method, "tools/call")) return failure(out, id, -32601, "Method not found");
const name = string(params, "name") orelse return failure(out, id, -32602, "Tool name is required");
diff --git a/src/mcp_server_app.zig b/src/mcp_server_app.zig
index a6956a6e..b5517953 100644
--- a/src/mcp_server_app.zig
+++ b/src/mcp_server_app.zig
@@ -35,21 +35,27 @@ pub fn catalog(a: std.mem.Allocator, source: []const u8, apps: bool) !Value {
return value;
}
-const template = @embedFile("mcp_task_app.html");
-const marker = "/* CODEGRAFF_THEME */";
-const theme_offset = std.mem.indexOf(u8, template, marker).?;
-const html = template[0..theme_offset] ++ @embedFile("ui_theme") ++ template[theme_offset + marker.len ..];
-
-const payload = .{ .contents = .{.{
- .uri = uri,
- .mimeType = mime,
- .text = html,
- ._meta = .{ .ui = .{
- .csp = .{ .connectDomains = [0][]const u8{}, .resourceDomains = [0][]const u8{} },
- .prefersBorder = true,
- } },
-}} };
-
-pub fn contents() @TypeOf(payload) {
- return payload;
+/// The page and its theme ship gzipped (build.zig); the theme is spliced in
+/// where the page marks it.
+pub fn contents(a: std.mem.Allocator) !Contents {
+ const gunzip = @import("update_archive.zig").gunzip;
+ const template = try gunzip(a, @embedFile("mcp_task_app.gz"));
+ const marker = "/* CODEGRAFF_THEME */";
+ const at = std.mem.indexOf(u8, template, marker).?;
+ const html = try std.mem.concat(a, u8, &.{ template[0..at], try gunzip(a, @embedFile("ui_theme.gz")), template[at + marker.len ..] });
+ return .{ .contents = .{.{ .text = html }} };
}
+
+pub const Contents = struct {
+ contents: [1]struct {
+ uri: []const u8 = uri,
+ mimeType: []const u8 = mime,
+ text: []const u8,
+ _meta: struct {
+ ui: struct {
+ csp: struct { connectDomains: [0][]const u8 = .{}, resourceDomains: [0][]const u8 = .{} } = .{},
+ prefersBorder: bool = true,
+ } = .{},
+ } = .{},
+ },
+};
diff --git a/src/mcp_server_tests.zig b/src/mcp_server_tests.zig
index fb8b9136..0b33d63b 100644
--- a/src/mcp_server_tests.zig
+++ b/src/mcp_server_tests.zig
@@ -264,6 +264,9 @@ test "MCP Apps negotiate metadata and serve only the declared resource" {
const resource = read.object.get("result").?.object.get("contents").?.array.items[0];
try std.testing.expectEqualStrings(app.mime, resource.object.get("mimeType").?.string);
try std.testing.expect(std.mem.startsWith(u8, resource.object.get("text").?.string, "<!doctype html>"));
+ // The gzipped theme is spliced into its slot, not left as the marker.
+ try std.testing.expect(std.mem.indexOf(u8, resource.object.get("text").?.string, "CODEGRAFF_THEME") == null);
+ try std.testing.expect(std.mem.indexOf(u8, resource.object.get("text").?.string, "Shared Codegraff desktop") != null);
const rejected = try std.json.parseFromSliceLeaky(Value, a, lines.next().?, .{});
try std.testing.expectEqual(@as(i64, -32002), rejected.object.get("error").?.object.get("code").?.integer);
}
diff --git a/src/prompt_content_tests.zig b/src/prompt_content_tests.zig
new file mode 100644
index 00000000..25f51491
--- /dev/null
+++ b/src/prompt_content_tests.zig
@@ -0,0 +1,63 @@
+//! Tests of the prompt TEXT itself: what the root and subagent prompts must
+//! say, and that the variants sliced from one string are the concatenations
+//! they replace. Split out of prompts.zig (600-line ceiling).
+
+const std = @import("std");
+const prompts = @import("prompts.zig");
+
+test "prompt variants sliced from one string equal their concatenations" {
+ try std.testing.expectEqualStrings(prompts.main_system_prompt ++ prompts.strict_note, prompts.main_system_prompt_strict);
+ try std.testing.expectEqualStrings(prompts.main_system_prompt_strict ++ prompts.ultracode_system_note, prompts.main_system_prompt_ultra_strict);
+ const joined = comptime blk: {
+ var out: []const u8 = "";
+ for (prompts.segments) |seg| out = out ++ seg.text;
+ break :blk out;
+ };
+ try std.testing.expectEqualStrings(prompts.main_system_prompt, joined);
+ for (prompts.segments, prompts.segment_table) |shared, own| try std.testing.expectEqualStrings(own.text, shared.text);
+}
+
+// The harness has always run a returned tool batch concurrently, for subagents
+// exactly as for the root (agent_tools.zig dispatches every external call as a
+// future before awaiting any). Nothing ASKED for a batch, though, so the
+// capability rode entirely on the model's own initiative - openai/codex spells
+// it out in its base instructions and graff did not. Pin it on BOTH prompts:
+// the subagent one is the easier of the two to forget, since it is five lines
+// long and does not share a base with the root.
+test "both prompts ask for parallel tool calls, with the dependency caveat" {
+ for ([_][]const u8{ prompts.main_system_prompt, prompts.sub_system_prompt, prompts.main_system_prompt_strict }) |p| {
+ try std.testing.expect(std.mem.indexOf(u8, p, "Parallelize tool calls") != null);
+ try std.testing.expect(std.mem.indexOf(u8, p, "ONE response") != null);
+ // Without the caveat this instruction is actively harmful: graff runs
+ // the whole batch concurrently, so two writes to one file would race.
+ try std.testing.expect(std.mem.indexOf(u8, p, "same file") != null);
+ try std.testing.expect(std.mem.indexOf(u8, p, "depends on an earlier") != null);
+ }
+ // Composing must not have cost either prompt its own identity.
+ try std.testing.expect(std.mem.indexOf(u8, prompts.sub_system_prompt, "subagent spawned by an orchestrator") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.sub_system_prompt, "do not broaden") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.sub_system_prompt, "Do not narrate") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.sub_system_prompt, "rlm(code)") == null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "Be direct and concise") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt_strict, "STRICT MODE") != null);
+}
+
+// #351: agent-authored PRs described only the diff, which a reviewer can already
+// read. The rationale — the failure mode, why this design, what it trades off —
+// exists only in the agent's head at authoring time and is unrecoverable later,
+// so the prompt has to demand it. The proportionality clause is load-bearing in
+// the other direction: without it a one-line typo fix grows four empty headings.
+test "root prompt (#351) requires what+why rationale in PR descriptions, scaled to the change" {
+ for ([_][]const u8{ "## What changed", "## Why", "Problem/failure mode", "Reason for this approach", "Constraints or trade-offs", "Rejected alternatives" }) |section|
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, section) != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "Scale the rationale to the change") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "never pad a small change with boilerplate") != null);
+}
+
+test "root prompt permits explicit external targets without weakening confinement" {
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "explicitly names") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "permission-gated bash") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "not covered by /rewind") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "Do not claim a relaunch is required") != null);
+ try std.testing.expect(std.mem.indexOf(u8, prompts.main_system_prompt, "Never extend") != null);
+}
diff --git a/src/prompts.zig b/src/prompts.zig
index 1459bf13..d6e91193 100644
--- a/src/prompts.zig
+++ b/src/prompts.zig
@@ -53,7 +53,7 @@ pub const Segment = struct { name: []const u8, text: []const u8, gate: Gate };
/// THE root prompt, in order. This table is the single source of both the
/// comptime full-capability constant and the runtime gated composition, so the
/// two can never drift apart or reorder relative to each other.
-pub const segments = [_]Segment{
+pub const segment_table = [_]Segment{
.{ .name = "intro", .text = text.intro_note, .gate = .always },
.{ .name = "local_tools", .text = text.local_tools_note, .gate = .local_tools },
.{ .name = "orchestration", .text = text.orchestration_note, .gate = .subagents },
@@ -77,12 +77,29 @@ pub const segments = [_]Segment{
.{ .name = "parallel_tail", .text = text.parallel_tail_note, .gate = .always },
};
-pub const main_system_prompt = blk: {
+/// The root prompt, then the strict and ultracode notes, as one string. The
+/// full prompt, its strict variant, the ultra-strict variant and every segment
+/// below are slices of it, so the binary carries the prompt text once rather
+/// than once per variant.
+const prompt_backing = blk: {
var out: []const u8 = "";
- for (segments) |seg| out = out ++ seg.text;
+ for (segment_table) |seg| out = out ++ seg.text;
+ break :blk out ++ strict_note ++ ultracode_system_note;
+};
+
+/// `segment_table` with each text pointing into `prompt_backing`.
+pub const segments = blk: {
+ var out = segment_table;
+ var at: usize = 0;
+ for (&out) |*seg| {
+ seg.text = prompt_backing[at..][0..seg.text.len];
+ at += seg.text.len;
+ }
break :blk out;
};
+pub const main_system_prompt = prompt_backing[0 .. prompt_backing.len - strict_note.len - ultracode_system_note.len];
+
/// One-shot (-p) sessions have no user to approve tool calls. The gate's REAL
/// map (agent_tool_gate.zig): at the ROOT, bash/edit_file/write_file and
/// unapproved MCP are auto-denied; SUBAGENTS skip the approval gate entirely
@@ -268,7 +285,7 @@ pub const strict_note =
\\attempt_completion with your final answer in the "result" field.
;
-pub const main_system_prompt_strict = main_system_prompt ++ strict_note;
+pub const main_system_prompt_strict = prompt_backing[0 .. main_system_prompt.len + strict_note.len];
/// Appended once to the active system-prompt variant when ultracode mode is
/// active (#326), instead of pasted onto every turn's user message the way
@@ -286,6 +303,10 @@ pub const ultracode_system_note =
\\
++ shapes.shape_catalog_note;
+/// `main_system_prompt_strict ++ ultracode_system_note`: Agent's comptime
+/// default for sys_ultra_strict.
+pub const main_system_prompt_ultra_strict = prompt_backing;
+
/// The exact condition the persistent-steering call sites (session_run.zig,
/// mainloop.zig) use to decide a turn is ultracode-steered: `/effort ultra`
/// sets reasoning == .ultra WITHOUT ultracode_mode, and the two toggle
@@ -482,51 +503,7 @@ test { // #421/#410: prompt snapshots and goal-prefix behavior must stay reachab
_ = @import("prompt_lean_tests.zig");
_ = @import("prompt_goal_tests.zig");
_ = @import("publication_policy_tests.zig");
-}
-
-// The harness has always run a returned tool batch concurrently, for subagents
-// exactly as for the root (agent_tools.zig dispatches every external call as a
-// future before awaiting any). Nothing ASKED for a batch, though, so the
-// capability rode entirely on the model's own initiative - openai/codex spells
-// it out in its base instructions and graff did not. Pin it on BOTH prompts:
-// the subagent one is the easier of the two to forget, since it is five lines
-// long and does not share a base with the root.
-test "both prompts ask for parallel tool calls, with the dependency caveat" {
- for ([_][]const u8{ main_system_prompt, sub_system_prompt, main_system_prompt_strict }) |p| {
- try std.testing.expect(std.mem.indexOf(u8, p, "Parallelize tool calls") != null);
- try std.testing.expect(std.mem.indexOf(u8, p, "ONE response") != null);
- // Without the caveat this instruction is actively harmful: graff runs
- // the whole batch concurrently, so two writes to one file would race.
- try std.testing.expect(std.mem.indexOf(u8, p, "same file") != null);
- try std.testing.expect(std.mem.indexOf(u8, p, "depends on an earlier") != null);
- }
- // Composing must not have cost either prompt its own identity.
- try std.testing.expect(std.mem.indexOf(u8, sub_system_prompt, "subagent spawned by an orchestrator") != null);
- try std.testing.expect(std.mem.indexOf(u8, sub_system_prompt, "do not broaden") != null);
- try std.testing.expect(std.mem.indexOf(u8, sub_system_prompt, "Do not narrate") != null);
- try std.testing.expect(std.mem.indexOf(u8, sub_system_prompt, "rlm(code)") == null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "Be direct and concise") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt_strict, "STRICT MODE") != null);
-}
-
-// #351: agent-authored PRs described only the diff, which a reviewer can already
-// read. The rationale — the failure mode, why this design, what it trades off —
-// exists only in the agent's head at authoring time and is unrecoverable later,
-// so the prompt has to demand it. The proportionality clause is load-bearing in
-// the other direction: without it a one-line typo fix grows four empty headings.
-test "root prompt (#351) requires what+why rationale in PR descriptions, scaled to the change" {
- for ([_][]const u8{ "## What changed", "## Why", "Problem/failure mode", "Reason for this approach", "Constraints or trade-offs", "Rejected alternatives" }) |section|
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, section) != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "Scale the rationale to the change") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "never pad a small change with boilerplate") != null);
-}
-
-test "root prompt permits explicit external targets without weakening confinement" {
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "explicitly names") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "permission-gated bash") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "not covered by /rewind") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "Do not claim a relaunch is required") != null);
- try std.testing.expect(std.mem.indexOf(u8, main_system_prompt, "Never extend") != null);
+ _ = @import("prompt_content_tests.zig");
}
// #326: setSystemPrompts is the single funnel every production site must go
diff --git a/src/schema_interactions.zig b/src/schema_interactions.zig
index 5fa62ba2..0e60162a 100644
--- a/src/schema_interactions.zig
+++ b/src/schema_interactions.zig
@@ -3,7 +3,7 @@
//!
//! Interactions declares a tool in the Responses shape minus `strict` (the
//! endpoint rejects the whole request on an unknown field), so it needs its
-//! own comptime catalogs rather than borrowing the Responses ones.
+//! own catalogs rather than borrowing the Responses ones.
const schema = @import("schema.zig");
const render = @import("schema_render.zig");
@@ -27,25 +27,53 @@ pub const tools_interactions_sub_optional_remote = interactionsToolsJson(base_op
/// The catalog a SUBAGENT is served, across both gates: `--no-local-tools`
/// subtracts, an available optional tool adds. Sole caller is Agent.toolsJson.
pub fn subToolsJson(kind: Provider.Kind, gated: bool) []const u8 {
- const optional = tool_gates.anyAvailable();
- return switch (kind) {
- .anthropic => if (gated)
- (if (optional) schema.tools_anthropic_sub_optional_remote else schema.tools_anthropic_sub_remote)
- else
- (if (optional) schema.tools_anthropic_sub_optional else schema.tools_anthropic_sub),
- .openai => if (gated)
- (if (optional) schema.tools_openai_sub_optional_remote else schema.tools_openai_sub_remote)
- else
- (if (optional) schema.tools_openai_sub_optional else schema.tools_openai_sub),
- .responses => if (gated)
- (if (optional) schema.tools_responses_sub_optional_remote else schema.tools_responses_sub_remote)
- else
- (if (optional) schema.tools_responses_sub_optional else schema.tools_responses_sub),
- .interactions => if (gated)
- (if (optional) tools_interactions_sub_optional_remote else tools_interactions_sub_remote)
- else
- (if (optional) tools_interactions_sub_optional else tools_interactions_sub),
+ return catalogFor(kind, gated, tool_gates.anyAvailable());
+}
+
+/// The plain catalogs stay comptime constants: they are also Agent's field
+/// defaults, so the binary carries them anyway. Every gated or optional
+/// variant is rendered on first use instead of compiled in, which keeps
+/// twelve near-copies of the catalog out of the binary.
+fn catalogFor(kind: Provider.Kind, gated: bool, optional: bool) []const u8 {
+ if (!gated and !optional) return switch (kind) {
+ .anthropic => schema.tools_anthropic_sub,
+ .openai => schema.tools_openai_sub,
+ .responses => schema.tools_responses_sub,
+ .interactions => tools_interactions_sub,
+ };
+ const variant: usize = if (!gated) 0 else if (optional) 1 else 2;
+ const specs: []const ToolSpec = switch (variant) {
+ 0 => &base_optional,
+ 1 => base_optional_remote,
+ else => base_remote,
+ };
+ return rendered(&cache[@backingInt(kind)][variant], kind, specs);
+}
+
+/// One rendered catalog per wire and variant, kept for the life of the
+/// process. Subagents start on worker threads, so the first render is
+/// published with a compare-and-swap and a losing racer frees its copy.
+var cache: [std.enums.values(Provider.Kind).len][3]std.atomic.Value(?*const []const u8) = @splat(@splat(.init(null)));
+
+fn rendered(cell: *std.atomic.Value(?*const []const u8), kind: Provider.Kind, specs: []const ToolSpec) []const u8 {
+ if (cell.load(.acquire)) |hit| return hit.*;
+ const gpa = std.heap.smp_allocator;
+ const shape = switch (kind) {
+ .anthropic => render.anthropic,
+ .openai => render.openai,
+ .responses => render.responses,
+ .interactions => render.interactions,
};
+ var aw: std.Io.Writer.Allocating = .init(gpa);
+ render.writeToolsJson(&aw.writer, shape, specs) catch @panic("out of memory");
+ const box = gpa.create([]const u8) catch @panic("out of memory");
+ box.* = aw.toOwnedSlice() catch @panic("out of memory");
+ if (cell.cmpxchgStrong(null, box, .acq_rel, .acquire)) |winner| {
+ gpa.free(box.*);
+ gpa.destroy(box);
+ return winner.?.*;
+ }
+ return box.*;
}
const std = @import("std");
@@ -61,3 +89,26 @@ test "the interactions catalog is the responses catalog without strict" {
defer responses_parsed.deinit();
try std.testing.expectEqual(responses_parsed.value.array.items.len, parsed.value.array.items.len);
}
+
+test "runtime-rendered subagent catalogs match the comptime ones byte for byte" {
+ const Case = struct { kind: Provider.Kind, gated: bool, optional: bool, want: []const u8 };
+ const cases = [_]Case{
+ .{ .kind = .anthropic, .gated = false, .optional = true, .want = schema.tools_anthropic_sub_optional },
+ .{ .kind = .anthropic, .gated = true, .optional = true, .want = schema.tools_anthropic_sub_optional_remote },
+ .{ .kind = .anthropic, .gated = true, .optional = false, .want = schema.tools_anthropic_sub_remote },
+ .{ .kind = .openai, .gated = false, .optional = true, .want = schema.tools_openai_sub_optional },
+ .{ .kind = .openai, .gated = true, .optional = true, .want = schema.tools_openai_sub_optional_remote },
+ .{ .kind = .openai, .gated = true, .optional = false, .want = schema.tools_openai_sub_remote },
+ .{ .kind = .responses, .gated = false, .optional = true, .want = schema.tools_responses_sub_optional },
+ .{ .kind = .responses, .gated = true, .optional = true, .want = schema.tools_responses_sub_optional_remote },
+ .{ .kind = .responses, .gated = true, .optional = false, .want = schema.tools_responses_sub_remote },
+ .{ .kind = .interactions, .gated = false, .optional = true, .want = tools_interactions_sub_optional },
+ .{ .kind = .interactions, .gated = true, .optional = true, .want = tools_interactions_sub_optional_remote },
+ .{ .kind = .interactions, .gated = true, .optional = false, .want = tools_interactions_sub_remote },
+ };
+ for (cases) |c| {
+ try std.testing.expectEqualStrings(c.want, catalogFor(c.kind, c.gated, c.optional));
+ // The second call is served from the cache, unchanged.
+ try std.testing.expectEqual(catalogFor(c.kind, c.gated, c.optional).ptr, catalogFor(c.kind, c.gated, c.optional).ptr);
+ }
+}
diff --git a/src/schema_render.zig b/src/schema_render.zig
index e49f1069..96b70634 100644
--- a/src/schema_render.zig
+++ b/src/schema_render.zig
@@ -1,67 +1,67 @@
//! Comptime provider-tool renderers: one ToolSpec list in, one provider-shaped
//! JSON tools array out. Split out of schema.zig (600-line ceiling) when the
//! optional-tool catalogs (#352 imagegen) doubled the number of comptime
-//! catalogs schema.zig has to hold. Pure comptime string building — no imports
-//! beyond std, so schema.zig can call these while building its own constants.
+//! catalogs schema.zig has to hold. String building with no imports beyond
+//! std, so schema.zig can call these while building its own constants;
+//! writeToolsJson is the runtime twin for catalogs rendered on demand.
//!
//! `specs` is `anytype` rather than `[]const schema.ToolSpec` only to avoid an
-//! import cycle back into schema.zig; every caller passes a comptime list of
+//! import cycle back into schema.zig; every caller passes a list of
//! structs with `.name`, `.desc` and `.schema`, and `.desc` must stay free of
//! characters needing JSON escapes (the descriptions are spliced in verbatim).
const std = @import("std");
-pub fn anthropicToolsJson(comptime specs: anytype) []const u8 {
+/// One tool entry in a provider's shape: `head` name `desc` description
+/// `schema` JSON-schema `tail`. The comptime catalogs and the runtime renderer
+/// both build from these pieces, so the two agree byte for byte.
+pub const Shape = struct { head: []const u8, desc: []const u8, schema: []const u8, tail: []const u8 };
+
+pub const anthropic: Shape = .{ .head = "{\"name\":\"", .desc = "\",\"description\":\"", .schema = "\",\"input_schema\":", .tail = "}" };
+pub const openai: Shape = .{ .head = "{\"type\":\"function\",\"function\":{\"name\":\"", .desc = "\",\"description\":\"", .schema = "\",\"parameters\":", .tail = "}}" };
+pub const responses: Shape = .{ .head = "{\"type\":\"function\",\"name\":\"", .desc = "\",\"description\":\"", .schema = "\",\"parameters\":", .tail = ",\"strict\":false}" };
+/// Google Interactions: the Responses shape minus `strict`. The endpoint
+/// validates strictly and rejects the whole request on an unknown field
+/// ("Unknown parameter 'strict' at 'tools[0]'"), so the two cannot share a
+/// catalog even though every other byte matches.
+pub const interactions: Shape = .{ .head = responses.head, .desc = responses.desc, .schema = responses.schema, .tail = "}" };
+
+fn toolsJson(comptime shape: Shape, comptime specs: anytype) []const u8 {
comptime {
var out: []const u8 = "[";
for (specs, 0..) |t, i| {
if (i > 0) out = out ++ ",";
- out = out ++ "{\"name\":\"" ++ t.name ++ "\",\"description\":\"" ++ t.desc ++
- "\",\"input_schema\":" ++ t.schema ++ "}";
+ out = out ++ shape.head ++ t.name ++ shape.desc ++ t.desc ++ shape.schema ++ t.schema ++ shape.tail;
}
return out ++ "]";
}
}
+pub fn anthropicToolsJson(comptime specs: anytype) []const u8 {
+ return toolsJson(anthropic, specs);
+}
+
pub fn openaiToolsJson(comptime specs: anytype) []const u8 {
- comptime {
- var out: []const u8 = "[";
- for (specs, 0..) |t, i| {
- if (i > 0) out = out ++ ",";
- out = out ++ "{\"type\":\"function\",\"function\":{\"name\":\"" ++ t.name ++
- "\",\"description\":\"" ++ t.desc ++ "\",\"parameters\":" ++ t.schema ++ "}}";
- }
- return out ++ "]";
- }
+ return toolsJson(openai, specs);
}
pub fn responsesToolsJson(comptime specs: anytype) []const u8 {
- comptime {
- var out: []const u8 = "[";
- for (specs, 0..) |t, i| {
- if (i > 0) out = out ++ ",";
- out = out ++ "{\"type\":\"function\",\"name\":\"" ++ t.name ++
- "\",\"description\":\"" ++ t.desc ++ "\",\"parameters\":" ++ t.schema ++
- ",\"strict\":false}";
- }
- return out ++ "]";
- }
+ return toolsJson(responses, specs);
}
-/// Google Interactions: the Responses shape minus `strict`. The endpoint
-/// validates strictly and rejects the whole request on an unknown field
-/// ("Unknown parameter 'strict' at 'tools[0]'"), so the two cannot share a
-/// catalog even though every other byte matches.
pub fn interactionsToolsJson(comptime specs: anytype) []const u8 {
- comptime {
- var out: []const u8 = "[";
- for (specs, 0..) |t, i| {
- if (i > 0) out = out ++ ",";
- out = out ++ "{\"type\":\"function\",\"name\":\"" ++ t.name ++
- "\",\"description\":\"" ++ t.desc ++ "\",\"parameters\":" ++ t.schema ++ "}";
- }
- return out ++ "]";
+ return toolsJson(interactions, specs);
+}
+
+/// The runtime twin of the comptime renderers, for catalogs not worth a
+/// compile-time copy in the binary.
+pub fn writeToolsJson(w: *std.Io.Writer, shape: Shape, specs: anytype) !void {
+ try w.writeByte('[');
+ for (specs, 0..) |t, i| {
+ if (i > 0) try w.writeByte(',');
+ for ([_][]const u8{ shape.head, t.name, shape.desc, t.desc, shape.schema, t.schema, shape.tail }) |part| try w.writeAll(part);
}
+ try w.writeByte(']');
}
test "renderers emit one entry per spec in each provider shape" {
@@ -72,17 +72,22 @@ test "renderers emit one entry per spec in each provider shape" {
};
// Comptime-only by construction: the catalogs are compile-time constants,
// so the call has to be forced into a comptime context here too.
- const anthropic = comptime anthropicToolsJson(&specs);
- const openai = comptime openaiToolsJson(&specs);
- const responses = comptime responsesToolsJson(&specs);
+ const anthropic_json = comptime anthropicToolsJson(&specs);
+ const openai_json = comptime openaiToolsJson(&specs);
+ const responses_json = comptime responsesToolsJson(&specs);
try std.testing.expectEqualStrings(
"[{\"name\":\"a\",\"description\":\"first\",\"input_schema\":{}},{\"name\":\"b\",\"description\":\"second\",\"input_schema\":{}}]",
- anthropic,
+ anthropic_json,
);
- try std.testing.expect(std.mem.indexOf(u8, openai, "\"type\":\"function\",\"function\":{\"name\":\"a\"") != null);
- try std.testing.expect(std.mem.endsWith(u8, responses, ",\"strict\":false}]"));
+ try std.testing.expect(std.mem.indexOf(u8, openai_json, "\"type\":\"function\",\"function\":{\"name\":\"a\"") != null);
+ try std.testing.expect(std.mem.endsWith(u8, responses_json, ",\"strict\":false}]"));
// Every rendered catalog must still parse as JSON.
- var parsed = try std.json.parseFromSlice(std.json.Value, std.testing.allocator, openai, .{});
+ var parsed = try std.json.parseFromSlice(std.json.Value, std.testing.allocator, openai_json, .{});
defer parsed.deinit();
try std.testing.expectEqual(@as(usize, 2), parsed.value.array.items.len);
+ // The runtime renderer writes the same bytes.
+ var aw: std.Io.Writer.Allocating = .init(std.testing.allocator);
+ defer aw.deinit();
+ try writeToolsJson(&aw.writer, responses, &specs);
+ try std.testing.expectEqualStrings(responses_json, aw.written());
}