feat(protocol): a canonical attribution-probe/v1 extension

[earakely-scale]

Summary

The A2A validator checks runtime attribution by asking an agent which project and task identifiers it last sent upstream, through urn:agentenv:attribution-probe/v1 at POST /ext/attribution-probe. Hand-written agents advertise that extension. An AgentEnvAgent cannot: reserved urn:agentenv: URIs must use their canonical SDK definition, and this one had none, so for SDK-built agents the check could only record "skipped".

This adds the canonical definition:

• ATTRIBUTION_PROBE_V1 has one runtime-owned operation, probe: a bodyless POST /ext/attribution-probe.
• Response. It answers with AttributionProbeResponse, {last_seen_attribution: {<dimension>: <value>}, last_seen_at_utc?}.
• Open map. last_seen_attribution is an open dict[str, str], like AgentEnv's cost attribution (agent_env.attribution.Attribution). The protocol assigns no keys; each deployment forwards whatever dimensions its model gateway understands. The validator keeps reading the project_id and task_id the control plane configures, so its check is unchanged.
• Registration. The extension is added to STANDARD_EXTENSIONS and exported from agentenv_protocol.a2a_agent.
• Opt-in. An agent declares it only by implementing the handler. The SDK records nothing itself, since only the agent knows what it sent.
• Docs. The README documents it next to MCP_CONFIG_V1, including that the answer is agent-wide and the route carries no access check of its own.

It is additive. No existing operation, route or card entry changes, and the plugin-API check reports no break.

Tests

• New tests in packages/agentenv-protocol/tests/test_a2a_agent.py:
  • the card advertises the endpoint;
  • probe returns the dimensions the agent last sent in a real task, including arbitrary ones, and {} before any are sent;
  • a request body is rejected with 400;
  • an undeclared response field is a 500 that does not echo the field;
  • an agent without the handler does not advertise the URI.
• Suites: packages/agentenv-protocol/tests has 288 passing; the related tst/unit A2A and validator tests have 227 passing.

🤖 Generated with Claude Code

Confidence Score: 3/5

The PR is not ready to merge because the Explorer can reject an embedded task or run the wrong task after browser navigation.

What we checked:

• Live spec version goes blank: No. The backend keeps the response key that the UI reads and looks up the renamed distribution.

Summary

Adds a canonical attribution probe that SDK-built agents can expose through the A2A protocol. The agent supplies the attribution it last sent; the SDK defines the response but does not record attribution itself.

• Adds the probe operation and response type to the shared extension catalog.
• Documents the open attribution map and agent-wide response, and adds coverage for handler behavior.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  H[Host or task URL] --> P[Explorer task runner]
  P --> A[Task API]
  A --> R[Run]
  R --> V[Run viewer]

Loading

_{Reviews (5) · Last reviewed commit: "Merge main into the attribution-probe ex..."}