Engine API: capability metadata mechanism

[Ricky-G]

Tracker: #2729
Epic: 0 (Engine API contract + reference adapter + gap fixes)
ADR reference: docs/adr/0028-agt-studio-unified-ui.md; mechanism specified by ADR 0029 (sibling issue, batch #2 (filed as #2787))
Template: Feature request

Filing metadata — Title: Engine API: capability metadata mechanism. Milestone: AGT Studio. Labels: enhancement, agent-mesh, architecture, Priority: HIGH.

Summary

Implement the capability-metadata mechanism that lets every Engine API route declare machine-readable capability flags. Studio's client allowlist is generated from this metadata, and the read-only invariant (umbrella non-negotiable #1) is enforced through it via a CI test in Epic 1d. Without this mechanism, the read-only invariant becomes a hand-maintained route allowlist, which the umbrella explicitly calls out as a foot-gun.

Scope

In scope

• A decorator or FastAPI dependency that attaches capability metadata to a route handler. Names and semantics come from ADR 0029; this issue implements them. Initial flag set:
  • runtime_mutating: bool — true if the call changes engine state, loaded policies, trust state, or any persisted artifact the engine treats as authoritative.
  • user_intent_required: bool — true if the call should not be triggered by a UI client without explicit user action (used by Studio to gate sensitive reads behind an explicit click rather than auto-poll).
  • read_only_surface: bool — true if the call is part of the read-only Studio surface. Mutually exclusive with runtime_mutating: true.
• Surfacing of capability metadata into the generated OpenAPI document as an extension key (e.g. x-agt-capability) so downstream client generators can read it without importing the Python package.
• A small Python helper exposing capability metadata for any FastAPI APIRouter / FastAPI app, callable from a CI test.
• Unit tests covering: decorator application, missing-flag detection (every route must declare flags; routes that forget are a CI error), conflict detection (runtime_mutating: true + read_only_surface: true is a CI error), OpenAPI extension key presence.
• Documentation under docs/studio/capability-metadata.md (or wherever ADR 0029 directs).

Out of scope

• The actual ADR document → batch Adding Microsoft SECURITY.MD #2 (filed as ADR 0029: Engine API contract for AGT Studio #2787).
• Applying the decorator to every existing endpoint → that work lives in batch build(deps): Bump scikit-learn from 1.3.2 to 1.5.0 in /packages/agent-os/modules/caas #4 (filed as Engine API: OpenAPI spec + reference adapter + /policies gap-fix #2791) (reference adapter ships routes already annotated).
• The CI test in Studio that asserts the generated client references zero runtime_mutating: true routes → Epic 1d.
• Generating the Studio TypeScript client from OpenAPI → Epic 1a / 1c.

Background / codebase grounding

• Existing endpoints that will be annotated (referenced in umbrella):
  • agent-governance-python/agent-mesh/src/agentmesh/server/policy_server.py:168 — GET /api/v1/policies → read_only_surface: true.
  • agent-governance-python/agent-mesh/src/agentmesh/server/policy_server.py:178 — POST /api/v1/policy/reload → runtime_mutating: true. Must be excluded from the Studio surface per umbrella non-negotiable This repo is missing a LICENSE file #1.
  • agent-governance-python/agent-mesh/src/agentmesh/server/sidecar.py:133 and :142 — duplicate annotations for the sidecar variant.
• The current code has no machine-readable distinction between read and write routes; that is exactly the gap this issue closes.

Dependencies

• Blocked by: batch Adding Microsoft SECURITY.MD #2 (filed as ADR 0029: Engine API contract for AGT Studio #2787) (ADR 0029) needs to freeze the flag names and OpenAPI extension key so this implementation lands against a stable contract.
• Blocks: batch build(deps): Bump scikit-learn from 1.3.2 to 1.5.0 in /packages/agent-os/modules/caas #4 (filed as Engine API: OpenAPI spec + reference adapter + /policies gap-fix #2791) (the reference adapter applies the decorator), batch build(deps-dev): Bump underscore from 1.13.7 to 1.13.8 in /packages/agent-os/extensions/cursor #5 (filed as Engine API: conformance test suite #2792) (the conformance suite asserts every route declares flags), Epic 1d (the CI invariant test in Studio reads the OpenAPI extension key and fails the build on any runtime_mutating: true route appearing in the generated client).

Deliverables

• New module under agent-governance-python/agent-mesh/src/agentmesh/server/capabilities.py (path subject to ADR 0029): decorator + helper + OpenAPI extension hook.
• Tests under agent-governance-python/agent-mesh/tests/server/test_capabilities.py.
• docs/studio/capability-metadata.md: short page on the model, how to apply, and how the CI invariant test consumes it.

Acceptance criteria

• Decorator or dependency implemented and unit-tested.
• Missing-flag and conflict-flag tests fail the suite (proves enforcement works).
• OpenAPI extension key appears on every annotated route (verified by a sample app in tests).
• Helper to enumerate routes + flags from a FastAPI app is exported (consumed by batch build(deps-dev): Bump underscore from 1.13.7 to 1.13.8 in /packages/agent-os/extensions/cursor #5 (filed as Engine API: conformance test suite #2792) and Epic 1d).
• Docs page describes the model in under 200 lines, with a worked example.
• Behavioral coverage: tests exercise decorator application, missing-flag detection, conflict detection (runtime_mutating: true + read_only_surface: true), OpenAPI extension-key surfacing, and route-enumeration helper. If the agent-mesh package has an existing coverage gate, this module meets it; do not introduce a new gate.
• Working agreements satisfied: linked from umbrella, milestone, labels, --body-file, rendered-description verification.

Notes for picking this up

• Keep the flag set small. Three flags is the entire MVP. New flags require an ADR amendment.
• The decorator should be fail-loud: if a route is registered without flags, the helper that enumerates routes must raise (or the OpenAPI generation must drop the route into a flagged-error bucket). The CI test in batch build(deps-dev): Bump underscore from 1.13.7 to 1.13.8 in /packages/agent-os/extensions/cursor #5 (filed as Engine API: conformance test suite #2792) should be able to catch this without grepping source.
• Do not couple this module to the dashboard or policy backends. It is a thin metadata helper on top of FastAPI.
• The OpenAPI extension key must be JSON-serializable so language-agnostic client generators (TypeScript in Studio, future Go/Rust adapters) can consume it without parsing Python.
• Working agreements for child issues apply: see umbrella section "Working agreements for issues filed under this tracker".

[github-actions]

🟡 Contributor Check: MEDIUM

Check	Result
Profile	MEDIUM
Credential	NONE
Overall	MEDIUM

Automated check by AGT Contributor Check.

[Ricky-G]

Closing — filed prematurely before maintainer walked through the plan. Will re-file after plan review.