feat(engine-api): add capability-metadata library for AGT Studio

[Ricky Gummadi (Ricky-G)]

Summary

Adds a small, reusable agentmesh.engine_api library that implements the capability-metadata substrate from the Engine API contract, so the future FastAPI reference adapter (issue #3) can declare each endpoint's three flags inline and emit them as the x-capability-flags OpenAPI extension. Library-only and purely additive: no HTTP routes are exposed and no existing source is modified.

Problem

The Studio contract (docs/studio/engine-api-contract.md sections 5 and 6) defines three per-endpoint capability flags and a read-only invariant, but there was no Python mechanism to declare them, emit them into the generated OpenAPI document, or machine-derive the read-only Studio client allowlist. Without this, the allowlist would be hand-maintained and the read-only rule would be unenforceable by CI (Epic 1d).

Changes

File	What changed
src/agentmesh/engine_api/capabilities.py	New CapabilityFlags Pydantic v2 model (frozen, three booleans) that enforces the read-only invariant read_only_surface == (not runtime_mutating) at construction, raising a clear ValueError; plus the capability_flags(...) decorator that validates and attaches flags under __capability_flags__.
src/agentmesh/engine_api/openapi.py	inject_capability_extension(app) overrides app.openapi to write x-capability-flags onto each operation and raises if a schema operation has no attached flags (fail loudly); derive_studio_client_allowlist(openapi_doc) returns sorted operationIds where runtime_mutating == false. FastAPI is lazy-imported.
src/agentmesh/engine_api/__init__.py	Public exports and package docstring documenting the attribute name and hook timing.
tests/engine_api/test_capabilities.py	Covers valid/invariant-violation flag construction, frozen model, decorator attachment and error path, and allowlist derivation (sorted output, policy_save exclusion, 12-of-13 fixture).
tests/engine_api/test_openapi.py	Builds a FastAPI app, asserts emission shape matches openapi.yaml, idempotency, the missing-flags raise, and end-to-end allowlist derivation.
tests/engine_api/__init__.py	Test package marker.

Design decisions

• Attribute name is __capability_flags__ (dunder, exported as CAPABILITY_FLAGS_ATTR).
• The model is frozen, so validated flags cannot be mutated post-construction.
• Pydantic v2, matching the rest of agent-mesh.
• FastAPI is not added to runtime dependencies: the agent-mesh pyproject.toml is a deprecation stub whose runtime deps only carry the -core redirect, and fastapi is already in the [dev] extra used by CI. The OpenAPI hook lazy-imports FastAPI instead.

Testing

• python -m ruff check --select E,F,W --ignore E501 .../engine_api .../tests/engine_api passes.
• python -m pytest tests/engine_api passes (22 passed).
• Verified the change is additive only (two new directories; no existing files modified).

Closes #3026

[github-actions]

🤖 AI Agent: code-reviewer — Action Items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 0 blockers, 1 warning. The PR introduces a well-structured and tested capability-metadata library for the Engine API, but the lack of explicit tests for edge cases in inject_capability_extension is a minor concern.

#	Sev	Issue	Where
1	Warn	No explicit tests for inject_capability_extension edge cases, such as routes without capability flags.	tests/engine_api/test_openapi.py

Action Items:

• None.

Warnings:

#	Description	Resolution
1	Add explicit tests for inject_capability_extension to ensure it raises ValueError when routes lack capability flags.	Fine as follow-up PRs.

[github-actions]

🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

• derive_studio_client_allowlist() in openapi.py -- implementation is incomplete.
• docs/studio/engine-api-contract.md -- sections 5 and 6 are referenced in the code and PR description, but the diff does not show any updates to these sections. Verify if they are up-to-date with the new CapabilityFlags model, capability_flags decorator, and inject_capability_extension function.
• README.md -- no updates are included in the diff to reflect the addition of the agentmesh.engine_api library and its public API.
• CHANGELOG.md -- missing an entry for the addition of the agentmesh.engine_api library and its new functionality.

[github-actions]

🤖 AI Agent: test-generator — `src/agentmesh/engine_api/capabilities.py`

AI-generated review output. Treat it as untrusted analysis and verify before acting.

src/agentmesh/engine_api/capabilities.py

• test_capability_flags_invalid_combination -- Validate that capability_flags decorator raises ValueError for invalid flag combinations.
• test_capability_flags_attribute_absence -- Ensure capability_flags decorator attaches the __capability_flags__ attribute correctly.

src/agentmesh/engine_api/openapi.py

• test_inject_capability_extension_missing_flags -- Verify inject_capability_extension raises ValueError when a route lacks capability flags.
• test_inject_capability_extension_partial_schema -- Test behavior when some routes are excluded from the OpenAPI schema.
• test_derive_studio_client_allowlist_invalid_schema -- Validate derive_studio_client_allowlist handles malformed or incomplete OpenAPI documents gracefully.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

🤖 AI Agent: security-scanner — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

No security issues found.

[github-actions]

🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

No breaking changes detected.

[github-actions]

PR Review Summary

Check	Status	Details
🔍 Code Review	⚠️ Missing	No current-run comment
🛡️ Security Scan	⚠️ Missing	No current-run comment
🔄 Breaking Changes	⚠️ Missing	No current-run comment
📝 Docs Sync	⚠️ Missing	No current-run comment
🧪 Test Coverage	⚠️ Missing	No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

[github-actions]

🟡 Contributor Check: MEDIUM

Check	Result
Profile	MEDIUM
Credential	LOW
Overall	MEDIUM

Automated check by AGT Contributor Check.

[Imran Siddique (imran-siddique)]

Reviewed. Clean implementation: frozen Pydantic model with the read-only invariant enforced at construction time, extra='forbid' prevents accidental extension, and the OpenAPI hook reads directly from __capability_flags__. No breaking changes — purely additive library. Merging; pre-existing dep-confusion-scan and docker-compose-test failures are not introduced here.