refactor: clean up OpenAPI schema for proper tags, summaries, and schemas

[markokraemer]

Summary

Deep cleanup of the OpenAPI spec generation so the auto-generated output is clean, navigable, and structurally correct. All changes are in the Rust source annotations; the JSON output follows automatically via the existing utoipa pipeline.

https://github.com/markokraemer/sandbox-agent/releases/download/pr-assets-openapi/openapi-docs-video.mp4

What changed

Domain-specific tags (was: everything under a single v1 tag)

All 71 operations are now grouped into 7 domain tags: health, desktop, agents, filesystem, processes, config, acp. This makes the API reference navigable in Swagger UI, Mintlify, and SDK generators.

Summaries and descriptions for every operation (was: 22 missing)

Added /// summary + /// description doc comments to all handlers that lacked them (health, agents, filesystem, config, ACP). The generated spec now has summary and description on every single operation.

Fixed 3 broken schema $ref targets (CRITICAL)

McpCommand, McpOAuthConfigOrDisabled, and McpRemoteTransport were referenced by McpServerConfig but never registered in ApiDoc. Also added McpOAuthConfig. All $ref targets now resolve correctly, and the hacky patch-openapi-types.mjs workarounds are no longer needed.

Removed 14 orphan schemas

Query-param structs like FsPathQuery, McpConfigQuery, ProcessListQuery etc. were registered in components/schemas but utoipa inlines them as individual parameters. Removed the dead schema registrations.

Correct content types for binary endpoints

Endpoint	Before	After
Screenshots	no content type	image/png
Recording download	no content type	video/mp4
File download	no content type	application/octet-stream
SSE stream	no content type	text/event-stream
File upload	text/plain	application/octet-stream
Tar upload	text/plain	application/x-tar

Improved info section

• Title: sandbox-agent -> Sandbox Agent
• Contact: now points to sandboxagent.dev
• License: added Apache-2.0 URL
• Server: added description "Local development server"

Build reliability

• build.rs now watches types.rs, desktop_types.rs, universal_events.rs, and the error crate (was only watching router.rs and lib.rs)
• Added /// descriptions to all 14 query parameters that lacked them

Files changed

• server/packages/sandbox-agent/src/router.rs - Tags, doc comments, content types, ServerAddon modifier
• server/packages/sandbox-agent/src/router/types.rs - Parameter description
• server/packages/sandbox-agent/src/desktop_types.rs - Parameter descriptions
• server/packages/openapi-gen/build.rs - Additional rerun-if-changed watches
• sdks/typescript/scripts/patch-openapi-types.mjs - Removed dead patches
• docs/openapi.json - Regenerated output

Verification

• cargo check passes
• cargo test -p sandbox-agent --lib - 22/22 pass
• swagger-cli validate - valid OpenAPI 3.0.3
• openapi-typescript generates correct types without patches

[markokraemer]

Before:

it was this mess