feat: add protoc-gen-connect-openapi to codegen pipeline

[haasonsaas]

Summary

• Adds sudorandom/protoc-gen-connect-openapi (269 stars, actively maintained) as a buf remote plugin
• Generates OpenAPI v3.1 specs from proto definitions into gen/openapi/
• Specs match the Connect-RPC wire format, consumable by mcp-openapi for MCP tool generation

Why

Currently only 8 of 22 proto packages have hand-written OpenAPI specs in platform/openapi/. The 14 missing services — including governance, approvals, objectives, prompts, traces, skills — are invisible to agents through MCP.

With this plugin, buf generate auto-produces OpenAPI for all 22 packages. No more manual spec authoring.

Follow-up

• After merge, run buf generate and verify output in gen/openapi/
• Wire gen/openapi/ specs into agent-mcp's mcp-openapi pipeline (may require a base template for auth/server info)
• The hand-written specs in platform/openapi/ can be gradually retired as the generated ones are validated
• Future: add protovalidate constraints to proto files — the plugin emits them as OpenAPI minimum, pattern, format: uuid etc.

Related issues

• evalops/platform#56 — Generate OpenAPI specs for governance, approvals, and objectives
• Publish generated TypeScript and Python clients as SDK packages #85 — Publish generated TypeScript and Python clients as SDK packages

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
Primarily adds a codegen plugin and checked-in generated OpenAPI artifacts; no runtime/business logic changes, but reviewers should watch for repo bloat and regeneration drift.

Overview
Adds community/sudorandom-connect-openapi to buf.gen.yaml so buf generate now emits Connect-RPC wire-format OpenAPI v3.1 specs into gen/openapi/.

Commits the generated OpenAPI YAML outputs (e.g., agents.v1, approvals.v1, attribution.v1, audit.v1, compliance.v1, config.v1, connectors.v1), enabling downstream tooling (like MCP tool generation) to consume service definitions without hand-written specs.

^{Reviewed by Cursor Bugbot for commit 3ed6af8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Empty path= option likely causes generation failure

High Severity

The opt for the OpenAPI plugin sets path= to an empty string. The path option in protoc-gen-connect-openapi specifies a single output filename (e.g., path=openapi.yaml). An empty value will either cause the plugin to attempt writing to an empty-named file (failing generation) or be a silent no-op, making the entire opt: block unnecessary dead configuration. If the intent was per-file output, the opt: section can be removed entirely. If a single merged file was intended, a filename is needed.

 

^{Reviewed by Cursor Bugbot for commit 1fedf36. Configure here.}

[cursor]

Bugbot Autofix determined this is a false positive.

The pinned protoc-gen-connect-openapi version treats path= as an empty Path, so buf generate succeeds and falls back to per-proto-file output.

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

^{Reviewed by Cursor Bugbot for commit 3ed6af8. Configure here.}

[cursor]

Streaming RPC produces empty path item in OpenAPI

Medium Severity

The server-streaming RPC ExportEvents (defined as returns (stream ExportEventsResponse) in the proto) generates an empty path item {} with no HTTP operations. While technically valid per OpenAPI 3.1, this means mcp-openapi will silently skip this endpoint when generating MCP tool definitions — the audit export functionality becomes invisible to agents. This is the only streaming RPC in the proto definitions, and the empty path item could also confuse or break some OpenAPI tooling that doesn't expect operation-less paths.

 

^{Reviewed by Cursor Bugbot for commit 3ed6af8. Configure here.}