docs: document every API operation and check the contract against the code - #253
Closed
AllureCurtain wants to merge 14 commits into
Closed
AllureCurtain wants to merge 14 commits into
AllureCurtain wants to merge 14 commits into
Conversation
Rewrite the handler annotations so each operation leads with one short sentence, groups its rules into lists and declares every status the handler writes. Correct the deployment model configuration PUT body, which named a nonexistent x_agents_core.model_configuration field. Add docs/api/request-conventions.md for the headers, JSON body checks and list parameters every /v1 operation shares, and regenerate the three OpenAPI contracts with make openapi.
Add contracts/agents-api/error-codes.md, which lists every error code Core, the console (including the installer rejections it relays for managed HTTPS setup) and the daemon transport write, and separates them from node diagnostics, Session diagnostic categories, Runtime protocol result codes and client-generated codes. contract_conformance_test.go requires every registry row to be written somewhere, every written status and code to have a row, and every annotated operation to declare the statuses its handler writes. core_resource_errors_test.go pins the Beta error fields of the Core Files and Skills routes. Link the registry from the Core error, admin, executor credential contracts and the API index.
A tag page carried up to 11 operations with full schemas, took 4-10 s to render and weighed 1.4-1.8 MB. Generate one page per operation in a folder per tag, keep an overview at the former tag URL, split each description into a lead and details, and stop generating TypeScript copies of every response schema. Sidebar links no longer prefetch. verify-api-copy checks folder navigation and overviews against the operation pages, verify-error-codes checks client-generated codes and every code the client and Web compare against, and the route gate accounts for the transport paths outside the OpenAPI contracts. Record keys are POSIX paths so generated records verify on Windows.
Nothing writes this code, and the registry check reported the stale row.
Rename "Agents API and Core API codes" to "HTTP API codes": its anchor tripped the retired-identifier name guard. List the sandbox_error and environment_connection_failed error objects the store records in Session events, and scan internal/store for them in the registry test. Scope out Turn error.code, which Core always publishes as internal_error. Add the console api-keys 404, the domain setup 405 and the installer artifact 405/404 responses; include unconfigured Runtime observation in execution_unavailable; correct which machine routes the OpenAPI publishes; and drop the list-query note from admin Files and Skills operations that are not lists.
Compare the installation domain setup table with the rejections deploy/install/ingress.py answers with before it accepts a request. The machine routes share the stored-error writer, so list /api/v1 for invalid_name, not_found_error, idempotency_conflict, executor_credential_exists and 409 sandbox_reset_in_progress, and /v1 for runtime_node_unavailable, with the machine-specific triggers. Widen turn_conflict to Environment file writes. Request conventions: the Environment files list also takes limit, and a mismatched scope header gets the rejected-key 401. Drop the U+0000 rule that Session metadata and Vault creation repeated.
An operation description in the contract is usually one long paragraph. The page opened with all of it, which pushed the request and response sections below the fold, and the contract text cannot be shortened without diverging from upstream. The reference now keeps the opening sentences under the title and folds the rest into a collapsed block, regrouped into short paragraphs at sentence boundaries. The contract prose itself stays verbatim, so the projection and verify:copy are unchanged.
Rebuild the API reference and guide pages from the current contracts after rebasing onto upstream main, including the folded operation descriptions and the per-operation pages.
Four fixes to the generated guide record and the checks around it. - The generated record in content/guide-sources.json no longer matched scripts/guides.json after the title escape was restored, so verify:docs failed and the two later verify steps never ran. Regenerated the guides. - The two new guides were absent from content/docs/meta.json, so fumadocs dropped them from the sidebar even though they were routable and linked. Listed them, and taught verify-docs-facts.mjs to fail when a page under content/docs is missing from that list. - docs/api/request-conventions.md claimed an operation page states only what differs from the conventions, although Files, Skills and Create a reusable Agent repeat a rule there. Stated the rule the pages follow. - The registry's Namespaces column was documentation only. A new conformance test rejects a cell that is empty, names something that is not a namespace or claims both "all" and a single namespace.
The execution-model page rendered docs/web/architecture.md, which carries a Mermaid fence the site cannot draw. It now renders docs/architecture.md, the architecture overview, so the page shows its three diagrams and no Mermaid fence is left anywhere on the site.
Upstream's Runtime MCP binding and workspace execution capabilities change edits the public contract, so two Session operation pages and the generated source records follow it.
The guide's URL named the old page rather than the document it now renders, so the slug, the sidebar entry, the browser check and the generated-copy allowlist follow the new name.
Nothing renders this file: the guide it was added for now embeds the repository diagrams next to their source.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The published API reference was thinner than the contracts it came from, and
nothing checked that either stayed true. This branch closes both gaps.
Contracts
services/agents-api/internal/apinow carries response anderror annotations, so
make openapipublishes what each operation can answerwith.
make openapiruns clean afterwards.contracts/agents-api/error-codes.mdis new: one registry of every error code,its HTTP status, and the namespaces whose routes can answer with it.
docs/api/request-conventions.mdis new: the rules that apply to every/v1operation, so an operation page only adds what it does differently.
contracts/agents-api/openapi.yaml,core.openapi.yaml,runtime.openapi.yamland
docs/api/README.mdmove together.Checks
apps/docs/scripts/verify-error-codes.mjscompares the registry with the codesthe handlers emit: 28 client-created codes through 3 forwarding helpers, and 24
compared codes. It is part of
pnpm verify.services/agents-api/internal/api/contract_conformance_test.gochecks theregistry against the registered routes, including that a
Namespacescellnames real namespaces or
all.services/agents-api/internal/api/core_resource_errors_test.gocovers the Coreresource error shape.
verify-contract-routes.py,verify-contract-freshness.mjs,verify-api-copy.mjsandverify-docs-facts.mjsgained the checks that wouldhave caught the gaps above.
Documentation site
38 tag overviews, up from 64 pages. Long operation descriptions fold at render
time.
docs/architecture.md, the documentCONTRIBUTING.mdnames as the architecture overview, instead ofdocs/web/architecture.md. That page is served at/architecture.Compatibility
No Go behavior changes: across the 29 touched handler files every changed line is
a comment, so only the generated contracts move. No dependency changes and no
lockfile change.
Verification
make openapi— no diffpnpm --dir apps/docs generate— 28 guides, 138 operation pages; stable when run twicepnpm --dir apps/docs verify— 138 operations, 28 + 24 error codes, 389 links across 204 pagespnpm --dir apps/docs test,typecheck,build— 204 routes prerenderedmake check— all targetsNeed help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.