Publish a versioned OpenAPI schema snapshot with documented compatibility

[mjacobs]

Publish a versioned OpenAPI schema snapshot with documented compatibility

I'm building an external read-only viewer for Kata, and wanted to generate a
typed client against the daemon's HTTP API. I found there's no published schema
to generate from — the only option is to hand-copy wire structs out of
internal/. This isn't viewer-specific: any out-of-process client that talks to
the daemon over HTTP hits the same wall, which is why I'm raising it as a
general API-contract gap rather than a one-off request.

(References below are against kenn-io/kata@3ec9d25, 2026-06-03; file paths
may drift, but the symbols/behavior are the stable part of the ask.)

Problem

Kata uses Huma internally, but the generated OpenAPI document is currently
disabled — internal/daemon/server.go sets humaConfig.OpenAPIPath = "" ("Plan
1: no /openapi.json"). External clients that want to generate typed clients
therefore have to hand-copy wire structs from internal/ packages (which are
not importable) and have no way to detect or fail clearly on an incompatible
daemon version.

Proposal

Publish the daemon's OpenAPI schema as a versioned snapshot with documented
compatibility expectations. This is intentionally framed as a versioned
snapshot per release with stated compatibility guarantees — not a promise of a
forever-stable API.

A versioned schema snapshot becomes the public contract for HTTP DTOs, so
external clients no longer depend on Kata's internal Go structs. This benefits
any generated-client workflow, not a single tool.

• Expose or export the OpenAPI document (re-enable OpenAPIPath, or provide
  a kata command / committed artifact that emits it).
• Commit or publish the schema artifact per release.
• Add docs or a command for regenerating it.
• Include daemon/API schema version in health/version output.
• Document compatibility expectations between client and daemon versions
  (what may change, and how breaking changes are signalled).

[mjacobs]

Opened #99 as a first implementation slice for this.

One note on framing, since the issue wording leans on "public contract": I'm treating that PR as a generated snapshot of the current daemon API — useful for client generation and review — rather than a compatibility guarantee or a commitment to support external daemon clients. The "documented compatibility" piece here, and surfacing the schema version in health, are intentionally left as follow-ups pending your preference on how far you'd want to take this.

The PR is deliberately easy to scope down — command-only without committing the artifact, publishing it only at release time, filtering which routes appear, or dropping the golden test — if any of those fit better. Happy to adjust to whatever direction you'd prefer.

[wesm]

Cool, makes sense to me. I have also been building a web UI (not read-only, most like something you could use as a personal todo list if you wanted in addition to viewing agent issues) for kata but am waiting to release it until it's a little more polished =) Having the OpenAPI schema available makes it easier for people to set up different viewers / interfaces to it .