Skip to content

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

Python

mcp: the first request carries every server that is ready

justrach8c92daffa9a9
diff --git a/docs/adr/0035-first-turn-skips-deferred-mcp-join.md b/docs/adr/0035-first-turn-skips-deferred-mcp-join.md
index 53807022..6d21d3f5 100644
--- a/docs/adr/0035-first-turn-skips-deferred-mcp-join.md
+++ b/docs/adr/0035-first-turn-skips-deferred-mcp-join.md
@@ -4,6 +4,8 @@ Status: accepted 2026-08-26
Later-request joining is updated by [ADR 0104](0104-live-publication-and-deferred-tool-evidence.md): only finished handshakes join before a model request.
+The first request is updated by [ADR 0221](0221-chatgpt-new-sign-in.md): it gives queued starts up to 100 ms and merges the ones that finished. A dormant server restored from cache starts in milliseconds; a real handshake still joins on a later request.
+
## Context
Interactive `--yolo` (including `graff acp`) starts MCP handshakes in the
diff --git a/docs/adr/0221-chatgpt-new-sign-in.md b/docs/adr/0221-chatgpt-new-sign-in.md
index 2ebc25b7..317eb1ef 100644
--- a/docs/adr/0221-chatgpt-new-sign-in.md
+++ b/docs/adr/0221-chatgpt-new-sign-in.md
@@ -145,6 +145,22 @@ process rather than restarting anything.
announced again; on any other route the items are removed and the tail
carries the tools as before. Before this, the MCP suite hit the cache on
12 to 29% of its input on this route against 60 to 65% on Codex.
+- **MiMo keeps `tools` frozen too.** MiMo's chat wire renders `tools` ahead
+ of the system prompt: a probe that appended one tool went from a full cache
+ hit to none, so every load re-billed the whole prompt. Chat has no
+ `additional_tools` item, but MiMo calls a tool that a system message
+ announces, so on MiMo routes the loaded tail rides one system message per
+ load, tagged so the tag never reaches the wire. MiMo's parser types arguments only for declared
+ tools and returns an announced tool's values as strings (`"5"`,
+ `"[\"a\"]"`); `tool_call_repair.retypeArgs` restores their schema types.
+ Other chat providers keep the tail until each is checked the same way.
+- **The first request carries every MCP server that is ready.** `-p` starts
+ MCP in the background and never waits out a handshake (ADR 0035). A server
+ restored from cache was ready before the first request, but that request
+ sent the catalog snapshot taken before the join, so `load_tool_schemas`'
+ listing grew on the second request: one sure cache miss per session on
+ every provider. The first request now gives queued starts up to 100 ms,
+ merges the finished ones, and sends the rebuilt catalog.
- **Transport**: live turns use the Responses WebSocket like codex, chaining
`previous_response_id` on the held socket, steering GPT-6 turns, and
prewarming when `GRAFF_WS_PREWARM` is set. One-shot and quiet turns stay on
diff --git a/src/agent_request.zig b/src/agent_request.zig
index 74a851e5..922053fc 100644
--- a/src/agent_request.zig
+++ b/src/agent_request.zig
@@ -99,10 +99,18 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
// Root and title requests rendezvous after launch-time CA loading.
http.waitForClientReady(self.io);
if (http.takeCaWarmFailure()) if (self.tracer) |tr| tr.note("ca_prewarm_failed", "CA bundle rescan failed; request will use lazy TLS initialization");
+ var tools_now = tools_in;
if (self.registry) |reg| {
+ const stale = self.toolsJson();
if (@import("mcp_pages.zig").beforeRequest(reg)) { // joins deferred starts, re-lists changed servers
self.invalidateRootTools();
try self.ensureRootTools(self.provider.kind);
+ // The caller's snapshot is the catalog that just went stale. Send the
+ // rebuilt one, or servers that joined miss this request and change
+ // `tools` on the next, throwing away the prompt cache (ADR 0221).
+ if (tools_now) |t| if (stale.len > 0 and t.ptr == stale.ptr) {
+ tools_now = self.toolsJson();
+ };
}
}
var budget_permit: ?run_budget_mod.Permit = null;
@@ -124,7 +132,7 @@ pub fn request(self: *Agent, tools_in: ?[]const u8) !std.json.ObjectMap {
// so the model lands a text answer now instead of asking for a tool the
// budget can never pay for — which is how the audit smoke died narrating.
// compaction/title requests pass tools=null already and skip this whole.
- var tools = try @import("jev_tool.zig").refreshCatalogForRequest(self, tools_in);
+ var tools = try @import("jev_tool.zig").refreshCatalogForRequest(self, tools_now);
if (self.tracer) |tr| {
if (tools) |t| if (t.len == 0) tr.note("tools", "empty catalog at request time (#695)");
}
diff --git a/src/mcp_boot.zig b/src/mcp_boot.zig
index f833f03b..1af17285 100644
--- a/src/mcp_boot.zig
+++ b/src/mcp_boot.zig
@@ -8,8 +8,8 @@
//! shorter: max(latency) instead of sum(latency).
//!
//! `--yolo` (including `-p`) sets `defer_join`: tasks start immediately but
-//! the first model call is not blocked. `joinBeforeRequest` merges them on
-//! later model calls as each handshake finishes (ADR 0035). Lean `-p` with no project `.mcp.json`
+//! the first model call is not blocked. `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` and teardown.
@@ -360,14 +360,18 @@ fn noteMcpDeferred(io: Io) void {
} });
}
-/// First model call: do not wait for deferred MCP handshakes (ADR 0035).
-/// Later requests only consume ready outcomes; `/mcp` and teardown may wait.
+/// 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);
const decision = firstRequestJoin(reg.pending_starts.len, &reg.first_request_join_skipped);
- const merged = if (decision == .join) joinReadyLocked(reg) else false;
+ const merged = if (decision != .none) joinReadyLocked(reg) else false;
+ const waiting = reg.pending_starts.len > 0;
reg.mutex.unlock(reg.io);
- if (decision == .skip) noteMcpDeferred(reg.io);
+ if (decision == .skip and waiting) noteMcpDeferred(reg.io);
return merged;
}
@@ -513,8 +517,7 @@ test "#860 later requests leave unfinished handshakes queued and consume ready t
const ready = try a.create(std.atomic.Value(bool));
ready.* = .init(true);
reg.pending_starts[1].ready = ready;
- try std.testing.expect(!joinBeforeRequest(&reg));
- try std.testing.expect(joinBeforeRequest(&reg));
+ try std.testing.expect(joinBeforeRequest(&reg)); // the first request merges the finished one, never the slow one
try std.testing.expect(!flag.load(.acquire));
try std.testing.expect(alreadyStarting(&reg, "slow"));
try std.testing.expect(!alreadyStarting(&reg, "ready"));
diff --git a/src/mcp_pages.zig b/src/mcp_pages.zig
index f4b1c60b..8e29cbd5 100644
--- a/src/mcp_pages.zig
+++ b/src/mcp_pages.zig
@@ -108,11 +108,32 @@ pub fn listen(server: *Server, a: Allocator) void {
/// re-list servers whose tools changed. True when the catalog must rebuild.
pub fn beforeRequest(reg: *mcp.Registry) bool {
const added = @import("mcp_watch.zig").poll(reg); // servers added mid-session
+ if (!reg.first_request_join_skipped) settle(reg, first_request_budget_ms);
const joined = @import("mcp_boot.zig").joinBeforeRequest(reg) or added;
const refreshed = refreshStale(reg);
return joined or refreshed;
}
+/// How long the first request gives queued starts. A dormant server restored
+/// from cache (mcp_lazy.zig) starts in milliseconds, and merging it on a later
+/// request would change the catalog mid-session and throw away the prompt
+/// cache (ADR 0221). A real handshake takes longer and still joins on a later
+/// request, as ADR 0035 has it.
+const first_request_budget_ms: u32 = 100;
+
+fn settle(reg: *mcp.Registry, budget_ms: u32) void {
+ var waited: u32 = 0;
+ while (waited < budget_ms) : (waited += 5) {
+ reg.mutex.lockUncancelable(reg.io);
+ const busy = for (reg.pending_starts) |t| {
+ if (t.ready) |flag| if (!flag.load(.acquire)) break true;
+ } else false;
+ reg.mutex.unlock(reg.io);
+ if (!busy) return;
+ reg.io.sleep(.fromMilliseconds(5), .awake) catch return;
+ }
+}
+
/// Re-list every server that announced a tool change. True when the
/// registry's tools changed, so the caller rebuilds the model's catalog.
pub fn refreshStale(reg: *mcp.Registry) bool {
@@ -134,3 +155,26 @@ pub fn refreshStale(reg: *mcp.Registry) bool {
}
return changed;
}
+
+test "the first request merges a start that finishes within its budget (ADR 0221)" {
+ const a = std.testing.allocator;
+ const io = std.testing.io;
+ const boot = @import("mcp_boot.zig");
+ var reg = mcp.Registry.empty(a, io);
+ defer reg.deinit();
+ const Task = struct {
+ fn run(task_io: Io, done: *std.atomic.Value(bool)) boot.StartOutcome {
+ defer done.store(true, .release);
+ task_io.sleep(.fromMilliseconds(20), .awake) catch {};
+ return .{};
+ }
+ };
+ const flag = try a.create(std.atomic.Value(bool));
+ flag.* = .init(false);
+ reg.pending_starts = try a.alloc(boot.PendingStart, 1);
+ reg.pending_starts[0] = .{ .future = try io.concurrent(Task.run, .{ io, flag }), .ready = flag };
+ reg.pending_names = try reg.arena().dupe([]const u8, &.{"dormant"});
+ settle(&reg, first_request_budget_ms);
+ try std.testing.expect(boot.joinBeforeRequest(&reg));
+ try std.testing.expectEqual(@as(usize, 0), reg.pending_starts.len);
+}