refactor(api): generate public contracts from official OpenAPI

.github/workflows/api-acceptance.yml

@@ -62,6 +62,7 @@ jobs:
           OAC_TEST_SERVER_BIN: ${{ runner.temp }}/oac-core-build/oac-core
           OAC_TEST_OFFICIAL_SDK_PYTHON: python
         run: |
+          python services/core/tests/official_schema_test.py
           python services/core/tests/official_client.py
           go test ./services/core/tests/integration -run '^(TestFunctionStateOfficialClientReadsAndLiveEvents|TestSavedReferenceRetryOfficialClient|TestAgentUpdateOfficialClient|TestAgentDeletionOfficialClient|TestSessionAgentFilterOfficialClient|TestSessionDeletionOfficialClient|TestEnvironmentInitialFailureOfficialClient|TestSelfHostedInitialCreationOfficialClient|TestSelfHostedCancellationOfficialClient)$' -count=1
       - uses: ./.github/actions/e2b-provider

AGENTS.md

@@ -25,7 +25,7 @@ Do not multiply entities without necessity. The long-term goal is minimal code,
 
 | Boundary | Protocol code | Protocol doc |
 | --- | --- | --- |
-| Application–Core (`/v1`) | Types in `contracts/agents-api/v1/` and route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) |
+| Application–Core (`/v1`) | Official schema pinned by `contracts/agents-api/upstream.json` plus Go-owned `x_agents_core` extensions; `make openapi` generates public Go types and `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) |
 | Web and operators–Core (`/core/v1`) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core administration API](contracts/agents-api/admin-api.md) |
 | Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](contracts/agents-api/machine-api.md) |
 | Core–Sandbox Provider | `services/core/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) |

Makefile

@@ -32,21 +32,29 @@ sqlc-generate:
 
 SWAG ?= go run github.com/swaggo/swag/cmd/swag@$(SWAG_VERSION)
 
-.PHONY: openapi
+.PHONY: openapi check-openapi
+OPENAPI_FLAGS ?=
+check-openapi:
+	$(MAKE) openapi OPENAPI_FLAGS=--check
+	python3 scripts/generate-public-api.test.py
+
 openapi:
+	python3 scripts/generate-public-api.py $(OPENAPI_FLAGS)
 	@set -e; root="$${OAC_DEV_HOME:-$$HOME/.oac}/build"; mkdir -p "$$root"; \
 	output=$$(mktemp -d "$$root/core-openapi.XXXXXX"); trap 'rm -rf "$$output"' EXIT; \
+	python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --swag-roots "$$output/roots.go"; \
 	$(SWAG) init \
-	    -g cmd/server/main.go --dir ./services/core,./contracts/agents-api/v1 \
+	    -g cmd/server/main.go --dir "./services/core,./contracts/agents-api/v1,$$output" \
 	    --output "$$output" \
 	    --outputTypes yaml --parseInternal; \
 	python3 scripts/patch-agents-openapi.py "$$output/swagger.yaml"; \
-	go run ./scripts/openapi-split "$$output/swagger.yaml" contracts/agents-api/openapi.yaml contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml
+	go run ./scripts/openapi-split $(OPENAPI_FLAGS) "$$output/swagger.yaml" "$$output/extensions.json" contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml; \
+	python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --extensions "$$output/extensions.json"
 
 check-sqlc:
 	python3 scripts/check-sqlc.py
 
-check-go:
+check-go: check-openapi
 	go test ./apps/daemon/... ./internal/... ./contracts/agents-api/... ./scripts/openapi-split -count=1
 
 .PHONY: check-runtime-contract