Publish an OpenAPI spec for the o2r relay API #59

New issue

Closed

opened 2026-06-05 02:44:58 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-05 02:44:58 +00:00

Owner

Summary

o2r (otel-a2a-relay) does not publish an OpenAPI spec for its relay API. It should.

Why

While researching Speakeasy's gram (their open-source MCP control plane), the analogy landed that o2r + mcporter together cover most of what gram does: o2r is the verified agent-to-agent channel (envelope verification, refuse-unverified, OTel observability), mcporter is the MCP discovery/management layer. The one piece gram has that o2r lacks is being OpenAPI-native: gram ingests an OpenAPI spec and generates typed tools, hosted endpoints, and contract tests from it.

o2r is the verification-and-audit relay, but its own request/response contract is implicit (defined in code, not as a spec). That blocks several things gram gets for free:

No machine-readable contract for the relay envelope and endpoints.
No generated clients / typed SDKs for callers filing request envelopes.
No contract tests against the relay surface.
Can't expose the relay itself as an MCP tool source cleanly (the gram pattern).

Proposed

Author an OpenAPI 3.1 spec for the o2r relay API (envelope submission, verification, status).
Wire it into CI as the source of truth for the request/response contract.
Optional follow-up: evaluate generating a typed client from it (Speakeasy-style) so callers stop hand-rolling envelopes.

Context

Surfaced out-of-band while prepping for a Speakeasy CEO interview (the cli-guard extension also builds on a Speakeasy OSS package). Filing so it doesn't get lost. Not urgent.

## Summary o2r (otel-a2a-relay) does not publish an OpenAPI spec for its relay API. It should. ## Why While researching Speakeasy's `gram` (their open-source MCP control plane), the analogy landed that o2r + mcporter together cover most of what gram does: o2r is the verified agent-to-agent channel (envelope verification, refuse-unverified, OTel observability), mcporter is the MCP discovery/management layer. The one piece gram has that o2r lacks is being **OpenAPI-native**: gram ingests an OpenAPI spec and generates typed tools, hosted endpoints, and contract tests from it. o2r is the verification-and-audit relay, but its own request/response contract is implicit (defined in code, not as a spec). That blocks several things gram gets for free: - No machine-readable contract for the relay envelope and endpoints. - No generated clients / typed SDKs for callers filing request envelopes. - No contract tests against the relay surface. - Can't expose the relay itself as an MCP tool source cleanly (the gram pattern). ## Proposed - Author an OpenAPI 3.1 spec for the o2r relay API (envelope submission, verification, status). - Wire it into CI as the source of truth for the request/response contract. - Optional follow-up: evaluate generating a typed client from it (Speakeasy-style) so callers stop hand-rolling envelopes. ## Context Surfaced out-of-band while prepping for a Speakeasy CEO interview (the cli-guard extension also builds on a Speakeasy OSS package). Filing so it doesn't get lost. Not urgent.

coilysiren added the

label

2026-06-17 07:04:31 +00:00

coilysiren commented

2026-06-17 08:23:43 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:23:43 +00:00