Add agent-level latency benchmark under fault conditions

[tomtom215]

Summary

This PR adds the first agent-level latency benchmark to the suite, measuring end-to-end latency through a 5-hop in-process coordinator chain as links become progressively unreliable. This addresses feedback that the existing 267 benchmarks measure only SDK-layer overhead (request encode, wire round-trip, task store contention) rather than the multi-agent coordination patterns that harness reviewers actually care about.

Key Changes

New Benchmark Infrastructure

• benches/benches/coordinator_chain_under_fault.rs — Main benchmark file with two groups:

  • coordinator_chain_5hop/latency_injection: Varies per-link latency (0–20 ms) with zero errors to isolate the chain's latency-compounding factor
  • coordinator_chain_5hop/error_injection: Varies per-link error rate (0–5%) with 3 retries per hop to measure steady-state latency under transient faults

• benches/src/coordinator.rs — Executor implementations:

  • ChainHopExecutor: Forwards incoming messages to the next hop via a pre-built A2aClient, emits Working → Completed status, and retries on transient errors
  • ChainLeafExecutor: Minimal leaf executor that emits Working → Completed

• benches/src/fault_transport.rs — FaultInjectingTransport wrapper:

  • Wraps any Transport implementation to inject synthetic latency and errors before delegation
  • Uses deterministic xorshift64 PRNG seeded per instance so criterion gets stable statistical estimates
  • Injects ClientError::Timeout (retryable) to exercise SDK retry paths faithfully

Documentation

• docs/adr/0008-agent-executor-trait-shape.md — ADR explaining why AgentExecutor uses manual Pin<Box<dyn Future>> instead of async fn:

  • Object safety is load-bearing: keeps RequestHandler and all downstream types non-generic
  • async fn in traits is not object-safe on stable Rust
  • Compensates with boxed_future() helper and agent_executor! macro for ergonomics

• Book updates — Added "Agent-Level Latency Under Fault" section to benchmark reference with honest caveats about in-process vs. real network faults

Example Updates

• examples/rig-agent/ — Reframed as an integration template rather than a working agent:
  • Clarifies that rig is intentionally not a dependency so the example builds without LLM SDK or API keys
  • run_rig_completion() returns a mock echo response by default
  • Includes snippet for users to add rig-core and replace the stub with real LLM calls

Security Hardening

• crates/a2a-server/src/push/sender.rs — DNS-rebinding defence improvements:
  • validate_webhook_url_with_dns() now returns Option<SocketAddr> (the validated IP to pin to)
  • New rewrite_uri_with_pinned_addr() function rewrites the outgoing URI to use the literal validated IP
  • New host_header_from_url() extracts the original hostname for the Host: header
  • Closes the TOCTOU window between validation and the HTTP client's own resolver by pinning the connection to the exact validated IP

Notable Implementation Details

• Deterministic fault injection: The FaultInjectingTransport uses an atomic counter fed through xorshift64 so the same benchmark variant gets the same sequence of fault decisions across runs, enabling stable criterion statistics
• Honest caveats: The benchmark documentation explicitly states this is in-process fault injection (synthetic Timeout before the wrapped transport is called), not real packet loss, so readers don't over-interpret the numbers
• Retry composition: Coordinators retry 3 times per hop; the bench harness retries 8 times at entry level so published error rates have effectively-zero unrecov

https://claude.ai/code/session_01MYSB9bmv8QVSyrfRzPsnMN