Generate Agent request shapes from the pinned schema

[SaladDay]

Summary

AGENTS.md says each rule has one authored definition, and that the /v1 schema is the pinned official one. Core used to validate Agent request bodies against a 70-line hand-written shape table. Its enums were also re-checked in the resolvers, and the generated Go tags held a third copy. This change makes the pinned schema the only source. This is T2b in the architecture audit.

• Generator. scripts/generate-public-api.py now generates services/core/internal/api/official_shapes.gen.go. That file holds the request shape trees of CreateAgentParams, UpdateAgentParams and SessionAgentConfigParam, taken from contracts/agents-api/upstream/openapi.json. It is part of make openapi and --check, so a pin bump regenerates it and CI catches drift. The generator refuses forms it can't project, such as an open object or a non-type discriminator.
• Walker. There is one walker, unchanged except for one capability: a map's values can have a shape. That covers metadata and headers. Core-extension shapes (x_agents_core, harness model providers) stay hand-written and reuse it.
• Validated once. The request shape is validated once, at the /v1 boundary. Resolvers keep only execution limits:
  • HTTP-only MCP, at most one tool_search declaration, service_tier=auto only, the nonempty model, the function count and name limits, and the URL and size limits.
  • The enum, transport, metadata, function-field and programmatic_tool_calling re-checks are deleted.
  • A saved Agent's stored tools are Core's own output, so the agent_id path does not re-check their shape. A decode failure there is storedDataError: logged, and returned as 500 internal_error without internals.

Behaviour

No input accepted before is rejected now. The blind review checked about 80 bodies against the baseline. The only widening is Session transport.authorization: null, which the pinned schema allows. Malformed input now gets the official field errors:

Case	Before	After
stdio transport without cwd	"MCP currently supports HTTP transport only."	"Missing required parameter: 'tools[0].transport.cwd'."
transport: {"type":"ws"}	HTTP-only message	"Invalid value: 'ws'. Supported values are: 'http' and 'stdio'."
"metadata":5	create invalid_request, update unsupported_or_invalid_configuration	both: invalid_request_error, param metadata
function missing name and description	tools[0].description	tools[0].name (schema order)
well-formed stdio	HTTP-only message	unchanged

The docs are updated to match: wire-semantics.md, execution-tools.md, and the coverage ledger in index.md (MCP is http only, and inline authorization is rejected), each with its zh mirror. official_mcp.py asserts the new errors.

Review

A fresh-context blind review found no must-fix. Its verdict was "merge after fixes".

• It compared every generated node to openapi.json by hand.
• Should-fixes: list the generated file in index.md, and map storedDataError on the Agent routes as well.
• Nits: one way to handle impossible decodes, logging the underlying error, a leftover bindings override, the generator's additionalProperties guard, test fixtures, a function-order test, and the ledger line.

All of these are fixed.

Checks

• go build ./..., vet and gofmt.
• make openapi (no diff), make check-openapi and the generator tests (12).
• internal/api and its importers against the DB: 3009 passed.
• The full tests/integration package with the pinned SDK: 390 passed.
• official_schema_test.py and official_client.py.
• make check-docs, the translation test and check-names.

Net: hand-written non-test −113, generated +210, tests +33.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}