Make tool schema & mcp_servers serialization deterministic (HashMap -> IndexMap)

[stephentoub]

Problem / root cause

Tool.parameters (and the mcp_servers config maps) used std::collections::HashMap. Rust's HashMap seeds its iteration order with a per-process random seed (SipHash RandomState), and serde_json serializes maps in iteration order — so each tool schema's top-level JSON keys came out byte-different every session (e.g. …"required":["url"],"type":"object"} one session vs …"type":"object",…,"required":["url"]} the next). That busts the model provider's prompt cache on the system+tools prefix, driving up cost and latency. Nested keys were already stable (they're serde_json::Value, whose default map is BTreeMap-sorted), matching the observed fingerprint: only top-level schema keys flipped. Rust was the only one of the six SDKs with this bug (Go/Java/.NET/Python/Node all use insertion- or sort-ordered maps).

Fix

Swap HashMap → indexmap::IndexMap for exactly the model-visible maps:

• Tool.parameters (+ skip_serializing_if = "IndexMap::is_empty")
• mcp_servers on SessionConfig / ResumeSessionConfig / CustomAgentConfig, the wire.rs SessionCreateWire / SessionResumeWire serialization structs, and the three with_mcp_servers setters
• tool_parameters / try_tool_parameters return types

indexmap is added with the serde feature (already a 2.14 transitive dep) and re-exported as github_copilot_sdk::IndexMap. Non-model-visible maps (MCP env/headers, system-message sections, telemetry, internal handler maps) are intentionally left as HashMap — they never reach the prompt prefix.

Result

Deterministic serialization. Top-level tool-schema keys are now stable (alphabetically sorted, since parameters round-trip through a BTreeMap-backed serde_json::Value); mcp_servers serialize in insertion order. We deliberately did not enable serde_json's preserve_order feature — it would add nested-key declared-order fidelity too, but at the cost of a global blast radius on every serde_json::Value map. The top-level container was the cache-buster, and it's fixed.

Tests

Two regression tests:

• tool_parameters_serialize_in_deterministic_order — builds a Tool 64× and asserts byte-identical serialization, plus pins the exact top-level key order.
• mcp_servers_serialize_in_insertion_order — inserts servers in non-sorted order, runs into_wire, and asserts the wire-JSON key positions follow insertion order.

Validation

From rust/:

• cargo build --all-features — ok
• cargo test --lib --all-features — 181 passed
• cargo test --doc --all-features — 23 passed
• cargo clippy --all-features --all-targets -- -D warnings — clean
• cargo +nightly-2026-04-14 fmt --check — clean

⚠️ BREAKING CHANGE

Public field/param/return types change from HashMap to IndexMap (Tool.parameters, the three mcp_servers fields + setters, and tool_parameters/try_tool_parameters). Migration is mechanical — IndexMap mirrors HashMap's API and is re-exported as github_copilot_sdk::IndexMap, so most consumers just swap the type name.

Generated by Copilot

[Copilot]

Pull request overview

This PR addresses nondeterministic JSON serialization in the Rust SDK that was caused by std::collections::HashMap iteration order, which in turn could invalidate provider-side prompt caching when tool schemas / MCP server maps are part of the model-visible prefix.

Changes:

• Replaces HashMap with indexmap::IndexMap for model-visible maps (Tool.parameters, and mcp_servers across session/agent config and wire serialization), and re-exports IndexMap from the crate root.
• Updates E2E tests and docs to use the new IndexMap-based API surface.
• Adds targeted regression tests to ensure deterministic tool-schema serialization and MCP server insertion-order serialization.

Show a summary per file

File	Description
rust/tests/e2e/rpc_mcp_lifecycle.rs	Updates test helper map type to IndexMap for MCP servers.
rust/tests/e2e/rpc_mcp_and_skills.rs	Updates MCP servers test helper map type to IndexMap.
rust/tests/e2e/pre_mcp_tool_call_hook.rs	Switches MCP servers map to IndexMap for hook-related E2E coverage.
rust/tests/e2e/mcp_oauth.rs	Updates MCP server config construction to IndexMap in OAuth lifecycle tests.
rust/src/wire.rs	Changes SessionCreateWire / SessionResumeWire mcp_servers to Option<IndexMap<...>> to keep serialization deterministic.
rust/src/types.rs	Updates public types/builders (Tool.parameters, SessionConfig / ResumeSessionConfig / CustomAgentConfig MCP server maps) and adds an insertion-order regression test.
rust/src/tool.rs	Updates tool_parameters / try_tool_parameters return types to IndexMap and adds deterministic serialization regression test.
rust/src/lib.rs	Re-exports IndexMap at github_copilot_sdk::IndexMap for consumer ergonomics.
rust/README.md	Documents the IndexMap choice and rationale (deterministic prompt-prefix bytes).
rust/Cargo.toml	Adds explicit indexmap dependency with serde feature.
rust/Cargo.lock	Records the new direct dependency inclusion.

Review details

• Files reviewed: 10/11 changed files
• Comments generated: 1
• Review effort level: Low

[stephentoub]

@tclem , any concerns? It is a breaking change, but in the past you've suggested that's acceptable.

[stephentoub]

@SteveSandersonMS any concerns?