Skip to content

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

Python

fix(mcp): snapshot published tools under registry lock

Rach Pradhanf050bfea4498
diff --git a/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md b/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md
index a363d7ad..5649548f 100644
--- a/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md
+++ b/docs/adr/0197-deferred-mcp-joins-are-registry-serial.md
@@ -14,8 +14,9 @@ can double-await the future or read its freed queue entry.
Use the registry mutex for every deferred queue mutation and join. Public
entry points take the lock; private helpers perform joins while it is held.
-Keep model requests nonblocking with respect to unfinished handshakes. Emit
-notices after releasing the lock.
+Tool-call lookup uses the same lock, and catalog readers copy the published
+tool slice while holding it. Keep model requests nonblocking with respect to
+unfinished handshakes. Emit notices after releasing the lock.
## Consequences
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 0b66bf28..096c2d79 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -221,7 +221,7 @@ record only when you need the evidence or the edge cases.
| [0193](0193-jev-selects-effort-only.md) | Optional Jev selects only supported session effort at the next request boundary; arbitrary judgments are not exposed. |
| [0194](0194-acp-child-sessions-are-an-opt-in-preview.md) | Draft ACP child sessions stream live only with explicit opt-in; durable replay is required before default enablement. |
| [0195](0195-embedded-browser-replaces-kuri.md) | Desktop browser uses embedded Chromium, web preview uses the paired extension, and CLI fetch uses built-in HTTP without a sidecar. |
-| [0197](0197-deferred-mcp-joins-are-registry-serial.md) | Deferred MCP startup queues and joins use the registry lock so concurrent parent and child requests consume each connection once. |
+| [0197](0197-deferred-mcp-joins-are-registry-serial.md) | Deferred MCP queues, joins, tool lookup, and catalog snapshots use the registry lock so concurrent requests consume and publish each connection once. |
## When to write one
diff --git a/src/agent_catalog.zig b/src/agent_catalog.zig
index bab6d80f..ef34b4bf 100644
--- a/src/agent_catalog.zig
+++ b/src/agent_catalog.zig
@@ -67,10 +67,10 @@ pub fn ensureRootTools(self: *Agent, kind: Provider.Kind) !void {
try surface.filterSpecs(@TypeOf(schema.base_specs[0]), self.arena, schema.base_specs[0..])
else
try withExtras(self.arena, try schema.effectiveRootSpecs(self.arena), self.provider);
- const connected: []const mcp.Tool = if (self.registry) |registry|
- (if (self.sub) try surface.filterWorkerMcp(self.arena, registry.tools) else registry.tools)
- else
- &.{};
+ const connected: []const mcp.Tool = if (self.registry) |registry| blk: {
+ const snapshot = try registry.snapshotTools(self.arena);
+ break :blk if (self.sub) try surface.filterWorkerMcp(self.arena, snapshot) else snapshot;
+ } else &.{};
dest.* = try schema.renderRootTools(self.arena, kind, specs, connected);
}
diff --git a/src/mcp.zig b/src/mcp.zig
index 1e8e5f53..808f84f5 100644
--- a/src/mcp.zig
+++ b/src/mcp.zig
@@ -253,6 +253,11 @@ pub const Registry = struct {
};
return n;
}
+ pub fn snapshotTools(reg: *Registry, allocator: Allocator) ![]Tool {
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
+ return allocator.dupe(Tool, reg.tools);
+ }
/// Spawn a stdio child and wire up its transport. Factored out of
/// `startServer` so the `GRAFF_MCP_PROBE` path can call it a second
/// time: some legacy SDK servers close stdout on an unrecognized
@@ -477,6 +482,8 @@ pub const Registry = struct {
return reg.callWithContext(out_alloc, qualified, input, null);
}
pub fn callWithContext(reg: *Registry, out_alloc: Allocator, qualified: []const u8, input: Value, context: ?@import("mcp_turn_context.zig").Snapshot) !CallResult {
+ reg.mutex.lockUncancelable(reg.io);
+ defer reg.mutex.unlock(reg.io);
const tool = for (reg.tools) |t| {
if (std.mem.eql(u8, t.qualified_name, qualified)) break t;
} else return .{ .text = try out_alloc.dupe(u8, "unknown MCP tool"), .is_error = true };
@@ -486,9 +493,6 @@ pub const Registry = struct {
const params = try @import("mcp_turn_context.zig").params(reg.gpa, server.name, tool.original_name, input, turn_ctx);
defer reg.gpa.free(params);
- reg.mutex.lockUncancelable(reg.io);
- defer reg.mutex.unlock(reg.io);
-
// Tool responses can be large and numerous; keep them out of the
// session arena. Only the returned text is copied to `out_alloc`.
var response_arena_state = std.heap.ArenaAllocator.init(reg.gpa);
diff --git a/src/mcp_boot.zig b/src/mcp_boot.zig
index 1738838f..5146617a 100644
--- a/src/mcp_boot.zig
+++ b/src/mcp_boot.zig
@@ -40,12 +40,14 @@ pub const StartOutcome = struct {
pub const PendingStart = struct {
future: Io.Future(StartOutcome) = .{ .any_future = null, .result = .{} },
ready: ?*std.atomic.Value(bool) = null,
+ await_entered: ?*Io.Event = null,
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);
@@ -475,6 +477,7 @@ test "concurrent parent and child requests consume a deferred handshake once" {
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 {
@@ -486,22 +489,21 @@ test "concurrent parent and child requests consume a deferred handshake once" {
}
};
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 };
+ 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 release: Io.Event = .unset;
+ var child_entered: Io.Event = .unset;
const Request = struct {
- fn run(task_io: Io, registry: *Registry, gate: *Io.Event) bool {
- gate.wait(task_io) catch return false;
+ 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, &reg, &release });
- var child = try io.concurrent(Request.run, .{ io, &reg, &release });
- release.set(io);
- // Keep the future outstanding while both request threads reach its join.
- try io.sleep(.fromMilliseconds(20), .awake);
+ var parent = try io.concurrent(Request.run, .{ io, &reg, null });
+ try awaiting.wait(io); // Parent holds the registry lock inside the join.
+ var child = try io.concurrent(Request.run, .{ io, &reg, &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);
@@ -509,6 +511,25 @@ test "concurrent parent and child requests consume a deferred handshake once" {
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(&.{}));
diff --git a/src/mcp_schema_gate.zig b/src/mcp_schema_gate.zig
index 7be3e0a0..676388bc 100644
--- a/src/mcp_schema_gate.zig
+++ b/src/mcp_schema_gate.zig
@@ -573,7 +573,8 @@ fn listing(arena: Allocator, all: []const mcp.Tool, unknown: []const []const u8)
pub fn handleLoad(agent: anytype, input: Value) ExecResult {
if (agent.sub) return .{ .text = "load_tool_schemas is root-only; a subagent has no MCP registry of its own", .is_error = true };
const reg = agent.registry orelse return .{ .text = "no MCP servers are connected, so there are no schemas to load", .is_error = true };
- const r = loadInto(agent.arena, reg.tools, input) catch
+ const catalog = reg.snapshotTools(agent.arena) catch return .{ .text = "load_tool_schemas failed to render the requested schemas", .is_error = true };
+ const r = loadInto(agent.arena, catalog, input) catch
return .{ .text = "load_tool_schemas failed to render the requested schemas", .is_error = true };
// Re-render the catalog so the provider sees the real schema too, not just
// the copy in this tool result.
diff --git a/src/mcp_select.zig b/src/mcp_select.zig
index bd11c7e3..00e83ab6 100644
--- a/src/mcp_select.zig
+++ b/src/mcp_select.zig
@@ -78,7 +78,8 @@ pub fn searchInto(arena: Allocator, all: []const mcp.Tool, input: Value) !mcp_sc
pub fn handleSearch(agent: anytype, input: Value) tools_mod.ExecResult {
if (agent.sub) return .{ .text = "mcp_search_tools is root-only; a subagent has no MCP registry of its own", .is_error = true };
const reg = agent.registry orelse return .{ .text = "no MCP servers are connected, so there are no tools to search", .is_error = true };
- const r = searchInto(agent.arena, reg.tools, input) catch
+ const catalog = reg.snapshotTools(agent.arena) catch return .{ .text = "mcp_search_tools failed", .is_error = true };
+ const r = searchInto(agent.arena, catalog, input) catch
return .{ .text = "mcp_search_tools failed", .is_error = true };
return .{ .text = r.text, .is_error = r.is_error };
}