[P0.7] Frozen Agent & Tool interfaces + contract tests

[vgtray]

Closes #7

Contrat FROZEN

• AgentInput/AgentOutput (pydantic 2.13.4): typed spine (incident_id, site_id, failure_family), citations (doc_id+section), confidence [0,1], extra=forbid anti-drift
• Agent Protocol async runtime_checkable — no inheritance required (proven by tests)
• Generic Tool Protocol + 3 concrete signatures DRAFT — @simerugby please review: CostQuery→CostReport, InventoryQuery→InventoryMatch, DispatchRequest→DispatchBooking
• EchoAgent reference impl (python -m contracts.echo_agent)

Tests

27 contract tests green (Protocol conformance, JSON round-trip for SSE, confidence bounds incl. NaN, extra=forbid, JSON schemas for all 6 tool models). pip-audit: 0 CVE.

@simerugby: tool signatures are DRAFT until your approval — if anything clashes with your backend plans, comment and we amend BEFORE anyone builds on them. Merged fast per hackathon flow, review post-merge welcome.

[Copilot]

Pull request overview

This PR introduces a “frozen” Python contract surface for Arc agents and tools, plus a reference EchoAgent and a contract-test suite to lock the interface (Issue #7 / P0.7) so agent and orchestrator work can proceed in parallel against stable I/O models and protocols.

Changes:

• Adds AgentInput/AgentOutput Pydantic models and Agent/generic Tool typing.Protocol contracts (runtime-checkable).
• Adds a minimal EchoAgent reference implementation and a comprehensive contract test suite validating protocol conformance, JSON round-trips, confidence bounds, and schema derivation.
• Adds contracts package exports, README guidance, and pinned runtime/dev dependencies for running the contracts/tests.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
contracts/agent_interface.py	Defines the frozen Agent I/O models and Agent/Tool protocols; includes draft tool model signatures.
contracts/echo_agent.py	Adds a minimal reference agent implementation for validating the Agent protocol end-to-end.
contracts/tests/test_agent_interface.py	Adds contract tests covering protocol conformance, JSON round-trips, validation constraints, and schema generation.
contracts/tests/init.py	Marks contracts.tests as a test-only package with a module docstring.
contracts/init.py	Establishes the package-level public import surface via re-exports.
contracts/README.md	Documents what is frozen vs draft and how to implement/run a conforming agent.
contracts/requirements.txt	Pins runtime dependency (pydantic) for the contracts surface.
contracts/requirements-dev.txt	Pins dev/test dependencies (pytest, pytest-asyncio) for the contracts test suite.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.