MCP lifecycle hardening, dispatch-only tool sources, compose spec caching (0.10.1)

[danielkov]

Hardens the MCP server lifecycle APIs around error paths and adds the primitives a lazy, on-demand connection strategy needs — driven by findings from an agent building exactly that on top of agentkit.

MCP lifecycle (agentkit-mcp)

• disconnect_server is now state-consistent on close failure: tools are always unregistered and ServerDisconnected always emitted; the close error is returned as advisory. Previously a failed close left stale, still-callable adapters in the catalog with no retry path (reattempt returned UnknownServer).
• unregister_server (new): fully removes a server — config, options, credentials — disconnecting first if live. Configs no longer accrete forever, and detached servers can't be resurrected by bulk connects.
• connect_servers_settled(ids) (new): settle-connect a chosen subset in parallel. Idempotent per server (already-connected handles are returned untouched, no re-handshake), unknown ids settle as UnknownServer failures, duplicates are attempted once. connect_all_settled now delegates to it.
• Replaced connections are gracefully closed on overwrite instead of silently dropped — plugs leaked Streamable HTTP server-side sessions on reconnect.
• McpServerHandle::tool_names() (new): list namespaced tool names without building adapters or cloning schemas.

Tool error vocabulary

McpToolAdapter collapsed every failure into ToolError::ExecutionFailed(String). Now:

• Io / Transport / Timeout → ToolError::Unavailable — "the connection is unhealthy", so reconnect logic can match on the variant instead of string-sniffing.
• JSON-RPC InvalidParams / InvalidRequest / ParseError → ToolError::InvalidInput — "fix your arguments", same feedback path as schema violations. Applies only when no McpErrorResponder synthesizes a result; responder behavior is untouched.
• Server-side and custom codes stay ExecutionFailed.

Tool sources (agentkit-tools-core, agentkit-tool-compose)

• Unadvertised<S> / ToolSource::unadvertised() (new): dispatch-only sources — specs() empty, get() passes through. Fills the gap between Filtered (hides dispatch too) and fully advertised sources.
• Compose spec caching: the compose description (which renders every child's output schema) was rebuilt on every specs() call — once per model step. It's now memoized and invalidated by drain_catalog_events, the same signal the loop uses to refresh the model-visible catalog, so the cache can never be staler than the model's view. Children wrapped with unadvertised() stay callable from scripts without being enumerated in the description.

Tests & snapshots

• New coverage: subset/idempotent settled connects, unregistration, disconnect against a dead server (via new HttpServerHandle::shutdown()), unadvertised dispatch end-to-end through a Lua script, spec-cache invalidation, and the error-mapping table.
• Snapshot recordings now canonicalise JSON key order: agent-client-protocol enables serde_json's preserve_order workspace-wide, so serialization order depended on the test binary's build graph (deterministic permission_deny failure, flaky after_tool_result). Stale recordings refreshed.

Version bumped to 0.10.1.

Also fixes the pre-existing agentkit-tool-fs replace_move_and_delete_work failure (stale assertion: in-tool permission denials surface as Failed, not FailedBeforeInvocation).