docs(openapi): Document All New Agent Session Endpoints in OpenAPI Spec

[sangalo20]

Overview

All new endpoints introduced by the Agent Auth proposal need to be reflected in the Broker and Gateway OpenAPI specifications so that client code can be generated and documentation stays accurate.

Endpoints to Document

nexus-broker (broker/openapi.yaml)

• POST /admin/v1/agents — Register agent
• GET /admin/v1/agents — List agents
• POST /v1/agent-sessions — Request scoped session
• POST /v1/agent-sessions/obo — Request OBO session
• GET /v1/agent-sessions/{session_id} — Get session
• DELETE /v1/agent-sessions/{session_id} — Close session

Gateway OpenAPI (openapi.yaml)

• Same endpoints proxied through the Gateway's /v1/ namespace
• Update generated client (nexus-gateway/pkg/broker/client.gen.go) via make generate

New schemas to define

• AgentRegistration (request)
• AgentProfile (response)
• AgentSessionRequest
• OBOSessionRequest
• AgentSessionResponse
• OBOSessionResponse

Acceptance Criteria

• All new endpoints documented in Broker OpenAPI spec
• All new schemas defined with required/optional fields
• make generate re-generates the Gateway client from the updated spec
• Existing tests still pass after codegen

Priority

P7 — Small effort

Reference

AGENT_AUTH_PROPOSAL.md — Implementation Priority