feat(interop): add A2A (Agent-to-Agent) protocol support

[5queezer]

Summary

• Base branch target: master
• Problem: ZeroClaw agents cannot discover or communicate with external agents — multi-agent is intra-instance only
• Why it matters: no standardized discovery or task delegation between instances
• What changed: native A2A protocol support — outbound client tool (src/tools/a2a.rs), inbound JSON-RPC 2.0 server (src/gateway/a2a.rs), auto-generated agent card, A2aConfig schema, same-host localhost A2A for multi-instance Pi setups
• What did not change: no SSE streaming, webhook push, mTLS/OAuth, or agent registry. Core agent loop unchanged — inbound tasks route through existing process_message pipeline

Label Snapshot

• Risk: high
• Size: M
• Scope: gateway, tool, config, onboard
• Module: tool: a2a, gateway: a2a

Change Metadata

• Type: feature
• Scope: multi

Linked Issue

• Closes [Feature][interop]: A2A (Agent-to-Agent) Protocol Support #3566
• Related feat: Agent-to-agent handoff and delegation #218, feat: agent-to-agent handoff and delegation #264, [supersede #1648] feat(tools): add inter-process communication tools #1668, feat(multi-agent): implement Phase 1 coordination system #2913, [Feature][interop]: A2A peer discovery for same-host and LAN #4643

Validation Evidence

cargo fmt --all -- --check                        # ✅
cargo clippy --all-targets -- -D warnings         # ✅
cargo test --lib -- gateway::a2a tools::a2a       # ✅ 40 tests pass

• 5 unit tests (agent card, URL validation, RPC error format, task store, MAX_TASKS)
• 15 handler integration tests (auth matrix, task lifecycle, capacity limit, message/send)
• 7 wiremock HTTP tests (discover, send, bearer auth, error codes)
• 8 tool execute tests (missing params, unknown action, read-only autonomy, SSRF)
• 1 allow_local test (localhost permitted when flag is set)
• 4 SSRF helper tests (cloud metadata, IPv4-mapped IPv6, resolution)
• E2E: five live instances on a Pi Zero 2 W communicating via A2A

Security Impact

• New permissions/capabilities? Yes
• New external network calls? Yes
• Secrets/tokens handling changed? Yes
• File system access scope changed? No

Mitigations:

• Outbound: SSRF protection (private IP blocking, IPv4-mapped IPv6, redirect policy, DNS resolution check). allow_local only when public_url points to localhost. Bearer tokens per-call, not logged.
• Inbound: GET /.well-known/agent-card.json unauthenticated (metadata only). POST /a2a requires bearer token (PairingGuard or a2a.bearer_token, constant-time comparison).
• TaskStore capped at 10,000 entries to prevent memory exhaustion.
• Localhost-only by default, fully opt-in (a2a.enabled = false).
• Startup warnings for missing auth and exposed internal addresses.
• Known residual: allow_local is a blanket bypass — peer allowlist planned in [Feature][interop]: A2A peer discovery for same-host and LAN #4643.

Privacy and Data Hygiene

• Status: pass
• No PII in agent cards or task responses. Bearer tokens excluded from tool output.

Compatibility / Migration

• Backward compatible? Yes
• Config changes? Yes — new optional [a2a] section with #[serde(default)]
• Migration needed? No

i18n Follow-Through

• Triggered? Yes
• Config reference updated for en, vi, zh-CN: Yes

Human Verification

• Verified: compilation, formatting, clippy, 40 tests
• Edge cases: missing params, unknown actions, invalid URL schemes, empty bearer tokens, disabled feature → 404, store full → 503
• E2E: five live Pi Zero 2 W instances (Kerf, Sentinel, Architect, Critic, Researcher) exchanging messages via A2A with gpt-5.1-codex-mini

Side Effects / Blast Radius

• Affected: gateway (2 routes), tool registry (1 conditional tool), config schema (1 section), onboard wizard (1 field), agent bootstrap prompt (1 tool description)
• Unintended effects: none — fully opt-in, routes return 404 when disabled

Rollback Plan

• Rollback: revert commit or set a2a.enabled = false
• Feature flag: a2a.enabled (default false)
• Failure symptoms: A2A routes returning errors, tool execution failures in agent logs

Risks and Mitigations

• Attack surface: localhost-only default, bearer auth on task endpoint, metadata-only agent card, disabled by default
• Resource exhaustion: MAX_TASKS = 10,000 cap; tasks go through process_message with existing rate limiting. TaskStore eviction planned in [Feature][interop]: A2A peer discovery for same-host and LAN #4643.
• SSRF via allow_local: blanket localhost bypass when public_url is local — peer allowlist planned in [Feature][interop]: A2A peer discovery for same-host and LAN #4643

[theonlyhennygod]

Hey @5queezer — this PR currently has failing CI checks. Could you rebase against current master and fix the failing checks so we can review and merge? Run cargo fmt --all -- --check && cargo clippy --all-targets -- -D warnings && cargo test locally before pushing. Thanks!

[5queezer]

Rebased onto master and all checks pass locally (fmt, clippy, test). This is intentionally scoped as an MVP. SSE streaming, multi-turn, and cancel are tracked in #3566 for follow-up PRs.

Tested manually via Telegram: single-turn A2A calls work between agents, each agent prints its reasoning to a shared group chat for verification. Happy to record a demo if helpful.