Skip to content

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

Python
24.2 KB
Raw Blame
//! 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(&reg);
        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(&reg);
    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, &reg.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(&reg, "codedbpro"));
    const pending = [_][]const u8{"codedbpro"};
    reg.pending_names = &pending;
    try std.testing.expect(alreadyStarting(&reg, "codedbpro"));
    try std.testing.expect(!alreadyStarting(&reg, "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(&reg));
    try std.testing.expect(!joinBeforeRequest(&reg));
}

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(&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"));
    try std.testing.expect(!joinBeforeRequest(&reg));
    release_task.set(io);
    try std.testing.expect(joinPending(&reg));
    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, &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);
    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"})));
}