graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! MCP registry boot: config load + the server connect fan-out, split from
//! mcp.zig under the 600-line ceiling (#123). The fan-out is the point: each
//! server's handshake is a network or process round trip, so connecting them
//! serially charged every startup the SUM of the latencies. They now run
//! concurrently (one `io.concurrent` task per server — `io.async` can run
//! inline and would serialize again) and merge in config order, so the
//! resulting tool list is identical to the serial build — only the wait is
//! shorter: max(latency) instead of sum(latency).
//!
//! Every session but `--json` sets `defer_join` (ADR 0230): tasks start at
//! once, nothing waits for them, and `joinBeforeRequest` merges each one that
//! has finished (ADR 0035, 0221). Lean `-p` with no project `.mcp.json` skips
//! imported global/plugin handshakes (ADR 0029 is the project file).
//! `joinPending` still blocks for `/mcp add|trust` and teardown.
const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const mcp = @import("mcp.zig");
const mcp_config = @import("mcp_config.zig");
const mcp_rpc = @import("mcp_rpc.zig");
const mcp_teardown = @import("mcp_teardown.zig");
const Registry = mcp.Registry;
/// One server's connect attempt. The server record and its tools live in a
/// PER-TASK arena — the registry arena is not thread-safe — and the arena
/// travels with the outcome so the registry can free it at deinit, after the
/// transports referencing it are torn down.
pub const StartOutcome = struct {
server: ?*mcp_rpc.Server = null,
tools: []mcp.Tool = &.{},
arena_state: ?std.heap.ArenaAllocator = null,
};
/// The flag has a stable address even when the pending queue grows. Only the
/// task writes it; the request thread consumes the future after acquire.
pub const PendingStart = struct {
future: Io.Future(StartOutcome) = .{ .any_future = null, .result = .{} },
ready: ?*std.atomic.Value(bool) = null,
await_entered: ?*Io.Event = null,
pub fn finished(self: *const PendingStart) bool {
return if (self.ready) |flag| flag.load(.acquire) else true;
}
fn awaitResult(self: *PendingStart, reg: *Registry) StartOutcome {
if (self.await_entered) |event| event.set(reg.io);
const result = self.future.await(reg.io);
self.future = .{ .any_future = null, .result = .{} };
if (self.ready) |flag| reg.gpa.destroy(flag);
self.ready = null;
return result;
}
};
const StartCtx = @import("mcp_start.zig").Ctx; // one start + its one retry
const startServerTask = @import("mcp_start.zig").task;
/// Load the workspace `.mcp.json` merged with the user-level global config,
/// then handshake every server CONCURRENTLY. Returns null (no error) when
/// neither file exists — MCP is optional. `global_path` is borrowed: it must
/// outlive the registry, which re-reads it on `/mcp trust`.
/// `defer_join` starts the handshakes but returns before they finish.
pub fn init(gpa: Allocator, io: Io, config_path: []const u8, global_path: ?[]const u8, home: []const u8, show_diagnostics: bool, environ_map: anytype, defer_join: bool) !?Registry {
var reg: Registry = .{
.gpa = gpa,
.io = io,
.home = home,
.arena_state = std.heap.ArenaAllocator.init(gpa),
.stdio_probe = if (environ_map.get("GRAFF_MCP_PROBE")) |v| !std.mem.eql(u8, v, "0") else true,
.lazy_stdio = environ_map.get("GRAFF_MCP_EAGER") == null,
.show_diagnostics = show_diagnostics,
.global_config_path = global_path,
.global_is_override = mcp_config.isEnvOverride(environ_map),
};
@import("mcp_lazy.zig").remember(environ_map); // the base each server `env` overlays
mcp_rpc.applyHandshakeTimeoutEnv(environ_map); // #275 GRAFF_MCP_HANDSHAKE_SECS + #327 GRAFF_MCP_PROBE_MS, on the same pass as the probe flag
errdefer reg.deinit();
const a = reg.arena();
const merged = mcp_config.load(io, a, Io.Dir.cwd(), config_path, global_path, home, reg.global_is_override);
if (!merged.found) {
reg.arena_state.deinit(); // nothing was started; no transports to tear down
return null;
}
// Collect the entries first, in config order: the fan-out consumes them
// concurrently, and a hash-map iterator is not a thing tasks can share.
const Entry = struct { name: []const u8, cfg: std.json.ObjectMap };
var entries: std.ArrayList(Entry) = .empty;
var it = merged.servers.iterator();
const state = @import("mcp_state.zig").load(io, a, home); // `graff mcp enable|disable`
while (it.next()) |entry| {
if (@import("mcp_state.zig").skipReason(state, entry.key_ptr.*, if (entry.value_ptr.* == .object) entry.value_ptr.*.object else null, environ_map, merged.isGlobalOnly(entry.key_ptr.*)) != .none) continue;
if (entry.value_ptr.* != .object) continue;
try entries.append(a, .{ .name = try a.dupe(u8, entry.key_ptr.*), .cfg = entry.value_ptr.*.object });
}
const futures = try gpa.alloc(PendingStart, entries.items.len);
@memset(futures, .{});
reg.pending_starts = futures; // errdefer must join every launched task
const started_names = try a.alloc([]const u8, entries.items.len);
@memset(started_names, "");
reg.pending_names = started_names;
var started: usize = 0;
for (entries.items) |e| {
const flag = try gpa.create(std.atomic.Value(bool));
flag.* = .init(false);
var ctx = startCtx(®);
ctx.ready = flag;
const args = .{ ctx, e.name, e.cfg };
const fut = io.concurrent(startServerTask, args) catch blk: {
if (defer_join) {
gpa.destroy(flag);
continue;
}
break :blk io.async(startServerTask, args);
};
futures[started] = .{ .future = fut, .ready = flag };
started_names[started] = e.name;
started += 1;
}
if (defer_join) return reg;
_ = joinPending(®);
return reg;
}
/// True when `name` is already live or queued on a deferred boot.
pub fn alreadyStarting(reg: *Registry, name: []const u8) bool {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
return alreadyStartingLocked(reg, name);
}
fn alreadyStartingLocked(reg: *const Registry, name: []const u8) bool {
for (reg.servers) |s| if (std.mem.eql(u8, s.name, name)) return true;
for (reg.pending_names) |n| if (std.mem.eql(u8, n, name)) return true;
return false;
}
fn startCtx(reg: *const Registry) StartCtx {
return .{ .gpa = reg.gpa, .io = reg.io, .home = reg.home, .show_diagnostics = reg.show_diagnostics, .stdio_probe = reg.stdio_probe, .lazy_stdio = reg.lazy_stdio };
}
/// Queue a stdio server onto `pending_starts` without waiting. Used by
/// companion auto-connect so first paint is not the handshake. If the
/// thread pool cannot take the task, skip — do not run `io.async` inline.
pub fn queueStdio(reg: *Registry, name: []const u8, command: []const u8, args: []const []const u8) void {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
if (alreadyStartingLocked(reg, name)) return;
const a = reg.arena();
var cfg: std.json.ObjectMap = .empty;
cfg.put(a, "command", .{ .string = a.dupe(u8, command) catch return }) catch return;
var argv = std.json.Array.init(a);
for (args) |arg| argv.append(.{ .string = a.dupe(u8, arg) catch return }) catch return;
cfg.put(a, "args", .{ .array = argv }) catch return;
_ = queueLocked(reg, name, cfg);
}
/// Queue any configured server (stdio or http) the same way (#1291). `cfg` is
/// copied into the registry arena: the task reads it after the caller's
/// request arena is gone. False when nothing was queued (no thread for the
/// task, or out of memory); a server already live or queued counts as queued.
pub fn queueConfig(reg: *Registry, name: []const u8, cfg: std.json.ObjectMap) bool {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
if (alreadyStartingLocked(reg, name)) return true;
const owned = cloneValue(reg.arena(), .{ .object = cfg }) catch return false;
return queueLocked(reg, name, owned.object);
}
fn cloneValue(a: Allocator, v: std.json.Value) Allocator.Error!std.json.Value {
return switch (v) {
.string => |s| .{ .string = try a.dupe(u8, s) },
.number_string => |s| .{ .number_string = try a.dupe(u8, s) },
.array => |arr| blk: {
var out = std.json.Array.init(a);
try out.ensureTotalCapacity(arr.items.len);
for (arr.items) |item| out.appendAssumeCapacity(try cloneValue(a, item));
break :blk .{ .array = out };
},
.object => |obj| blk: {
var out: std.json.ObjectMap = .empty;
var it = obj.iterator();
while (it.next()) |e| try out.put(a, try a.dupe(u8, e.key_ptr.*), try cloneValue(a, e.value_ptr.*));
break :blk .{ .object = out };
},
else => v,
};
}
fn queueLocked(reg: *Registry, name: []const u8, cfg: std.json.ObjectMap) bool {
const a = reg.arena();
const n = a.dupe(u8, name) catch return false;
// Reserve both paired arrays before spawning: allocation failure must not
// abandon a task that still borrows registry configuration.
const old = reg.pending_starts;
const next = reg.gpa.alloc(PendingStart, old.len + 1) catch return false;
const names = a.alloc([]const u8, old.len + 1) catch {
reg.gpa.free(next);
return false;
};
const flag = reg.gpa.create(std.atomic.Value(bool)) catch {
reg.gpa.free(next);
return false;
};
flag.* = .init(false);
var ctx = startCtx(reg);
ctx.ready = flag;
const fut = reg.io.concurrent(startServerTask, .{ ctx, n, cfg }) catch {
reg.gpa.destroy(flag);
reg.gpa.free(next);
return false;
};
@memcpy(next[0..old.len], old);
next[old.len] = .{ .future = fut, .ready = flag };
@memcpy(names[0..old.len], reg.pending_names);
names[old.len] = n;
if (old.len > 0) reg.gpa.free(old);
reg.pending_starts = next;
reg.pending_names = names;
return true;
}
/// Wait at most `budget_ms` for the named queued handshakes, then merge every
/// finished one (#1291). A server that is still connecting stays queued and
/// joins on a later request, like the rest of a deferred boot.
pub fn joinNamedWithin(reg: *Registry, names: []const []const u8, budget_ms: u32) bool {
var waited: u32 = 0;
while (waited < budget_ms and anyNamedPending(reg, names)) : (waited += 20)
reg.io.sleep(.fromMilliseconds(20), .awake) catch break;
return joinReady(reg);
}
fn anyNamedPending(reg: *Registry, names: []const []const u8) bool {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
for (reg.pending_starts, 0..) |*task, i| {
if (task.ready == null or task.finished() or i >= reg.pending_names.len) continue;
for (names) |n| if (std.mem.eql(u8, n, reg.pending_names[i])) return true;
}
return false;
}
fn mergeOutcomes(reg: *Registry, futures: []PendingStart) void {
const a = reg.arena();
var servers: std.ArrayList(*mcp_rpc.Server) = .empty;
var tools: std.ArrayList(mcp.Tool) = .empty;
var task_arenas: std.ArrayList(std.heap.ArenaAllocator) = .empty;
servers.appendSlice(a, reg.servers) catch {};
tools.appendSlice(a, reg.tools) catch {};
task_arenas.appendSlice(a, reg.task_arenas) catch {};
for (futures) |*fut| {
const outcome = fut.awaitResult(reg);
const server = outcome.server orelse continue;
// A companion (eager codedb-pro) or /mcp trust can connect this server
// while its deferred start is still in flight. Appending the outcome
// anyway advertises every tool twice, and a strict Responses endpoint
// (xAI) rejects the whole request over one duplicate (#505). First
// registration wins; tear the latecomer down but keep its arena in
// task_arenas so its memory follows the normal teardown lifecycle.
var already_connected = false;
for (servers.items) |existing| {
if (std.mem.eql(u8, existing.name, server.name)) {
already_connected = true;
break;
}
}
if (already_connected) {
mcp_rpc.deinitServer(server, reg.io, .init(reg.io, mcp_teardown.teardown_grace));
if (outcome.arena_state) |ta| task_arenas.append(a, ta) catch {};
continue;
}
const server_index = servers.items.len;
servers.append(a, server) catch continue;
for (outcome.tools) |*tool| tool.server_index = server_index;
tools.appendSlice(a, outcome.tools) catch {};
if (outcome.arena_state) |ta| task_arenas.append(a, ta) catch {};
}
reg.servers = a.dupe(*mcp_rpc.Server, servers.items) catch reg.servers;
reg.tools = a.dupe(mcp.Tool, tools.items) catch reg.tools;
reg.task_arenas = a.dupe(std.heap.ArenaAllocator, task_arenas.items) catch reg.task_arenas;
}
/// Pure policy for the first model call after a deferred MCP boot. The
/// handshake tasks are already running; waiting here is the delay before
/// any native tool can start. Skip once, then join.
pub fn firstRequestJoin(pending_len: usize, already_skipped: *bool) enum { none, skip, join } {
if (pending_len == 0) return .none;
if (!already_skipped.*) {
already_skipped.* = true;
return .skip;
}
return .join;
}
pub fn isAcp(positionals: []const []const u8) bool {
return positionals.len > 0 and std.mem.eql(u8, positionals[0], "acp");
}
/// ADR 0230: every session connects MCP in the background, interactive
/// (after consent) as well as `--yolo`, `-p` and ACP, so no handshake holds up
/// the start. `--json` keeps a blocking connect so the protocol stream does
/// not race a late catalog merge; ACP shares its stdout but must stay live.
pub fn deferMcpJoin(json_mode: bool, acp: bool) bool {
return !json_mode or acp;
}
/// Lean `-p` connects workspace `.mcp.json` (ADR 0029). It does not handshake
/// imported global/plugin servers when the project file is empty — that was
/// the exact-reply wall tax vs OpenCode `--pure`.
pub fn oneshotSkipsImportedMcp(oneshot: bool, lean: bool, project_servers: usize) bool {
return oneshot and lean and project_servers == 0;
}
/// No model request waits out a deferred MCP handshake (ADR 0035), but each
/// merges the ones already finished, the first included: a dormant server
/// restored from cache that merged later would change the catalog mid-session
/// and throw away the prompt cache (ADR 0221; mcp_pages.settle gives the first
/// request 100 ms for it). `/mcp` and teardown may wait.
pub fn joinBeforeRequest(reg: *Registry) bool {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
const decision = firstRequestJoin(reg.pending_starts.len, ®.first_request_join_skipped);
// Queued for the root request to report (mcp_connect_notice.drain).
if (decision != .none) reg.connect_notices.collect(reg); // named before the merge consumes them
const merged = if (decision != .none) joinReadyLocked(reg) else false;
if (merged) reg.connect_notices.resolve(reg);
if (decision == .skip and reg.pending_starts.len > 0) reg.connect_notices.still_connecting = true;
return merged;
}
/// Compact unfinished tasks in place without changing their flag addresses.
/// No unfinished handshake is ever awaited on the request path.
pub fn joinReady(reg: *Registry) bool {
reg.mutex.lockUncancelable(reg.io);
defer reg.mutex.unlock(reg.io);
return joinReadyLocked(reg);
}
fn joinReadyLocked(reg: *Registry) bool {
const pending = reg.pending_starts;
var merged = false;
for (pending, 0..) |*task, i| {
if (task.ready == null or !task.finished()) continue;
mergeOutcomes(reg, pending[i..][0..1]);
merged = true;
}
// Keep the allocation until every task is consumed; names for consumed
// slots are blanked so failed connections can be retried while others wait.
var waiting = false;
for (pending, 0..) |task, i| {
if (task.ready != null) {
waiting = true;
} else if (i < reg.pending_names.len) {
@constCast(reg.pending_names)[i] = "";
}
}
if (!waiting and pending.len > 0) {
reg.gpa.free(pending);
reg.pending_starts = &.{};
reg.pending_names = &.{};
}
return merged;
}
/// Await deferred startServer tasks and append them to the live registry
/// (companion servers may already be present). Idempotent. Returns true
/// when this call actually merged something, so the agent can rebuild catalogs.
pub fn joinPending(reg: *Registry) bool {
const t0 = Io.Timestamp.now(reg.io, .awake);
reg.mutex.lockUncancelable(reg.io);
const joined = joinPendingLocked(reg);
reg.mutex.unlock(reg.io);
if (!joined) return false;
const waited = @max(0, t0.untilNow(reg.io, .awake).toMilliseconds());
if (waited >= 80) {
if (@import("engine_sink.zig").hostedSink()) |sink| {
var buf: [80]u8 = undefined;
const text = std.fmt.bufPrint(&buf, "MCP connect waited {d}ms", .{waited}) catch "";
if (text.len > 0) sink.emit(reg.io, .{ .session_notice = .{ .text = text, .tone = .dim } });
}
}
return true;
}
fn joinPendingLocked(reg: *Registry) bool {
if (reg.pending_starts.len == 0) return false;
const futures = reg.pending_starts;
reg.pending_starts = &.{};
reg.pending_names = &.{};
mergeOutcomes(reg, futures);
reg.gpa.free(futures);
return true;
}
test "MCP boot fans server handshakes out with io.concurrent" {
const src = @embedFile("mcp_boot.zig");
try std.testing.expect(std.mem.indexOf(u8, src, "io.concurrent(startServerTask") != null);
try std.testing.expect(std.mem.indexOf(u8, src, "io.async(startServerTask") != null);
try std.testing.expect(std.mem.indexOf(u8, src, "defer_join") != null);
}
test "defer_join does not fall back to inline io.async" {
const src = @embedFile("mcp_boot.zig");
try std.testing.expect(std.mem.indexOf(u8, src, "gpa.destroy(flag);") != null);
}
test "alreadyStarting sees pending names before the handshake finishes" {
const io = std.testing.io;
var reg = Registry.empty(std.testing.allocator, io);
defer reg.deinit();
try std.testing.expect(!alreadyStarting(®, "codedbpro"));
const pending = [_][]const u8{"codedbpro"};
reg.pending_names = &pending;
try std.testing.expect(alreadyStarting(®, "codedbpro"));
try std.testing.expect(!alreadyStarting(®, "other"));
reg.pending_names = &.{};
}
test "joinPending is a no-op on an empty registry" {
const io = std.testing.io;
var reg = Registry.empty(std.testing.allocator, io);
defer reg.deinit();
try std.testing.expect(!joinPending(®));
try std.testing.expect(!joinBeforeRequest(®));
}
test "firstRequestJoin skips once, then joins" {
var skipped = false;
try std.testing.expectEqual(.none, firstRequestJoin(0, &skipped));
try std.testing.expect(!skipped);
try std.testing.expectEqual(.skip, firstRequestJoin(2, &skipped));
try std.testing.expect(skipped);
try std.testing.expectEqual(.join, firstRequestJoin(2, &skipped));
try std.testing.expectEqual(.none, firstRequestJoin(0, &skipped));
}
test "deferMcpJoin: every session but --json connects in the background (ADR 0230)" {
try std.testing.expect(deferMcpJoin(false, false)); // interactive, --yolo, -p
try std.testing.expect(!deferMcpJoin(true, false)); // --json
}
test "oneshotSkipsImportedMcp is lean -p with no project .mcp.json" {
try std.testing.expect(oneshotSkipsImportedMcp(true, true, 0));
try std.testing.expect(!oneshotSkipsImportedMcp(true, true, 1)); // ADR 0029
try std.testing.expect(!oneshotSkipsImportedMcp(true, false, 0)); // --no-lean
try std.testing.expect(!oneshotSkipsImportedMcp(false, true, 0)); // REPL
}
test "#860 later requests leave unfinished handshakes queued and consume ready tasks" {
const a = std.testing.allocator;
const io = std.testing.io;
var reg = Registry.empty(a, io);
defer reg.deinit();
var release_task: Io.Event = .unset;
defer release_task.set(io);
const flag = try a.create(std.atomic.Value(bool));
flag.* = .init(false);
reg.pending_starts = try a.alloc(PendingStart, 2);
@memset(reg.pending_starts, .{});
reg.pending_names = try reg.arena().dupe([]const u8, &.{ "slow", "ready" });
const Task = struct {
fn run(task_io: Io, release: *Io.Event, done: *std.atomic.Value(bool)) StartOutcome {
defer done.store(true, .release);
release.waitTimeout(task_io, .{ .duration = .{ .raw = .fromSeconds(5), .clock = .awake } }) catch {};
return .{};
}
};
reg.pending_starts[0] = .{ .future = try io.concurrent(Task.run, .{ io, &release_task, flag }), .ready = flag };
const ready = try a.create(std.atomic.Value(bool));
ready.* = .init(true);
reg.pending_starts[1].ready = ready;
try std.testing.expect(joinBeforeRequest(®)); // the first request merges the finished one, never the slow one
try std.testing.expect(!flag.load(.acquire));
try std.testing.expect(alreadyStarting(®, "slow"));
try std.testing.expect(!alreadyStarting(®, "ready"));
try std.testing.expect(!joinBeforeRequest(®));
release_task.set(io);
try std.testing.expect(joinPending(®));
try std.testing.expectEqual(@as(usize, 0), reg.pending_starts.len);
}
test "concurrent parent and child requests consume a deferred handshake once" {
const io = std.testing.io;
var reg = Registry.empty(std.testing.allocator, io);
defer reg.deinit();
reg.first_request_join_skipped = true;
const ready = try reg.gpa.create(std.atomic.Value(bool));
ready.* = .init(false);
var completed: Io.Event = .unset;
var awaiting: Io.Event = .unset;
var release_start: Io.Event = .unset;
defer release_start.set(io);
const Start = struct {
fn run(task_io: Io, flag: *std.atomic.Value(bool), done: *Io.Event, release: *Io.Event) StartOutcome {
flag.store(true, .release);
done.set(task_io);
release.wait(task_io) catch {};
return .{};
}
};
reg.pending_starts = try reg.gpa.alloc(PendingStart, 1);
reg.pending_starts[0] = .{ .future = try io.concurrent(Start.run, .{ io, ready, &completed, &release_start }), .ready = ready, .await_entered = &awaiting };
reg.pending_names = try reg.arena().dupe([]const u8, &.{"server"});
try completed.wait(io);
var child_entered: Io.Event = .unset;
const Request = struct {
fn run(task_io: Io, registry: *Registry, entered: ?*Io.Event) bool {
if (entered) |event| event.set(task_io);
return joinBeforeRequest(registry);
}
};
var parent = try io.concurrent(Request.run, .{ io, ®, null });
try awaiting.wait(io); // Parent holds the registry lock inside the join.
var child = try io.concurrent(Request.run, .{ io, ®, &child_entered });
try child_entered.wait(io); // Child has reached the contested join call.
release_start.set(io);
const parent_merged = parent.await(io);
const child_merged = child.await(io);
try std.testing.expect(parent_merged != child_merged);
try std.testing.expectEqual(@as(usize, 0), reg.pending_starts.len);
}
test "catalog snapshot stays stable when a registry publishes new tools" {
const io = std.testing.io;
var reg = Registry.empty(std.testing.allocator, io);
defer reg.deinit();
var initial = [_]mcp.Tool{.{
.server_index = 0,
.original_name = "read",
.qualified_name = "mcp__fixture__read",
.description = "Read",
.input_schema = .null,
}};
reg.tools = &initial;
const snapshot = try reg.snapshotTools(std.testing.allocator);
defer std.testing.allocator.free(snapshot);
reg.tools = &.{};
try std.testing.expectEqual(@as(usize, 1), snapshot.len);
try std.testing.expectEqualStrings("mcp__fixture__read", snapshot[0].qualified_name);
}
test "ACP stdout discipline does not block optional startup handshakes" {
try std.testing.expect(isAcp(&.{"acp"}));
try std.testing.expect(!isAcp(&.{}));
try std.testing.expect(!isAcp(&.{ "repl", "acp" }));
try std.testing.expect(deferMcpJoin(true, isAcp(&.{"acp"})));
try std.testing.expect(!deferMcpJoin(true, isAcp(&.{"repl"})));
}