fred-runtime 3.3.6__tar.gz → 3.4.0__tar.gz

{fred_runtime-3.3.6 → fred_runtime-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fred-runtime
-Version: 3.3.6
+Version: 3.4.0
 Summary: Runtime adapters and infrastructure wiring for Fred v2 agents.
 Author-email: Thales <noreply@thalesgroup.com>
 License: Apache-2.0

{fred_runtime-3.3.6 → fred_runtime-3.4.0}/fred_runtime/__main__.py

@@ -77,7 +77,6 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "dump-openapi":
         return _cmd_dump_openapi(args)
     parser.error(f"unknown command: {args.command}")
-    return 2
 
 
 if __name__ == "__main__":

{fred_runtime-3.3.6 → fred_runtime-3.4.0}/fred_runtime/app/agent_app.py

@@ -56,9 +56,9 @@ from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, status
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from fred_core.common.config_loader import get_config
-from fred_core.common.team_id import is_personal_team_id, personal_team_id
 from fred_core.history.history_schema import ChatMessage
 from fred_core.kpi import KPIMiddleware
+from fred_core.kpi.kpi_runtime_stage_metric import runtime_stage_timer
 from fred_core.kpi.kpi_writer_structures import KPIActor
 from fred_core.logs.audit_log import emit_audit_log
 from fred_core.logs.log_setup import log_setup
@@ -89,6 +89,7 @@ from fred_sdk.contracts.context import (
     PortableContext,
     PortableEnvironment,
     RuntimeContext,
+    TeamOperationRouteRule,
 )
 from fred_sdk.contracts.eval import EvalStep, EvalTrace
 from fred_sdk.contracts.execution import (
@@ -146,8 +147,13 @@ from fred_runtime.runtime_support.checkpoints import load_checkpoint
 from ..common.structures import AgentSettingsLike
 from ..integrations.inprocess_toolkit_registry import build_inprocess_toolkit
 from ..integrations.v2_runtime.adapters import (
+    AgentConfigAssetsAdapter,
     CompositeToolInvoker,
+    DocumentContentAdapter,
+    DocumentFolderAdapter,
     DocumentSearchAdapter,
+    DocumentSummarizeAdapter,
+    DocumentTreeAdapter,
     FredKnowledgeSearchToolInvoker,
     FredMcpToolProvider,
     FredWorkspaceFs,
@@ -734,6 +740,16 @@ def _build_runtime_services(
         binding=binding,
         settings=settings,
     )
+    # Companion document-access ports: tree listing + on-demand summarization,
+    # same private-binding doctrine as the search adapter.
+    document_tree = DocumentTreeAdapter(
+        binding=binding,
+        settings=settings,
+    )
+    document_summarize = DocumentSummarizeAdapter(
+        binding=binding,
+        settings=settings,
+    )
     tool_provider = FredMcpToolProvider(
         binding=binding,
         settings=settings,
@@ -784,6 +800,14 @@ def _build_runtime_services(
         checkpointer=runtime_config.checkpointer,
         agent_invoker=agent_invoker,
         document_search=document_search,
+        # #1903 capability ports: per-instance config assets (template fetch at
+        # tool time), image-document raw fetch, and folder listing. Same
+        # private-binding doctrine as document_search.
+        agent_assets=AgentConfigAssetsAdapter(binding=binding, settings=settings),
+        document_content=DocumentContentAdapter(binding=binding, settings=settings),
+        document_folders=DocumentFolderAdapter(binding=binding, settings=settings),
+        document_tree=document_tree,
+        document_summarize=document_summarize,
     )
 
 
@@ -945,6 +969,66 @@ class _McpCatalogResponse(BaseModel):
     servers: list[_McpCatalogEntry]
 
 
+class _ModelCatalogEntry(BaseModel):
+    id: str
+    provider: str
+    name: str
+    description: str | None = None
+    profile_ids: list[str] = Field(default_factory=list)
+    """Every `models_catalog.yaml` profile_id sharing this entry's
+    (provider, name) — TEAM-ROUTING-POLICY-RFC.md §7.1's id-space
+    translation: a routing policy picks by profile_id (finer-grained than
+    this capability id), so control-plane needs a way back from profile_id
+    to capability id for write-time enablement validation, and the
+    team-settings picker needs the reverse (which profile_ids this enabled
+    capability actually offers). Declaration order in the source YAML,
+    first-seen first — same order `default_profile_by_capability` favors."""
+
+
+class _ModelCatalogResponse(BaseModel):
+    models: list[_ModelCatalogEntry]
+
+
+def _project_model_catalog_entries(catalog: Any) -> list[_ModelCatalogEntry]:
+    """One `_ModelCatalogEntry` per distinct (provider, name) pair in a
+    loaded `ModelCatalog` (OBSERV-02 v3, `AGENT-CAPABILITY-RFC.md` §8.7).
+
+    Pulled out of `get_models_catalog` as a pure function so it is directly
+    unit-testable without a running app (`agent_app.py` has no existing
+    FastAPI TestClient harness — building one just for this route would be
+    disproportionate; this function is where the actual logic worth testing
+    lives). `catalog` is typed `Any` here to avoid a module-level
+    `..model_routing` import (see the route's own lazy import for why);
+    callers pass a real `ModelCatalog`.
+    """
+    from fred_sdk.contracts.capability.manifest import model_capability_id
+
+    seen: dict[tuple[str, str], _ModelCatalogEntry] = {}
+    for profile in catalog.profiles:
+        provider = profile.model.provider
+        name = profile.model.name
+        # ModelProfile.validate_model (contracts.py) already guarantees both
+        # are non-empty strings for every profile that exists — asserted
+        # (not a skip/continue) so this narrows the type instead of hiding
+        # an invariant violation the validator itself is supposed to prevent.
+        assert provider and name, (
+            f"ModelProfile {profile.profile_id!r} passed validation without provider/name"
+        )
+        key = (provider, name)
+        existing = seen.get(key)
+        if existing is None:
+            seen[key] = _ModelCatalogEntry(
+                id=model_capability_id(provider, name),
+                provider=provider,
+                name=name,
+                description=profile.description,
+                profile_ids=[profile.profile_id],
+            )
+        else:
+            existing.profile_ids.append(profile.profile_id)
+    return list(seen.values())
+
+
 class _ResolvedAgentInstance(BaseModel):
     agent_instance_id: str
     template_agent_id: str
@@ -1098,7 +1182,9 @@ async def _resolve_agent_instance(
     registry: Mapping[str, ReActAgentDefinition | GraphAgentDefinition],
     access_token: str | None,
     control_plane_url: str | None,
+    http_client: httpx.AsyncClient,
     team_id: str | None = None,
+    request_id: str | None = None,
 ) -> _ResolvedExecutionTarget:
     """
     Resolve a direct or managed execution target into a concrete definition.
@@ -1173,9 +1259,17 @@ async def _resolve_agent_instance(
         f"{control_plane_url.rstrip('/')}/teams/{team_id}/agent-instances/"
         f"{request.agent_instance_id}/runtime"
     )
-    headers = {"Authorization": f"Bearer {access_token}"} if access_token else None
-    async with httpx.AsyncClient(timeout=10.0) as client:
-        response = await client.get(url, headers=headers)
+    headers: dict[str, str] = {}
+    if access_token:
+        headers["Authorization"] = f"Bearer {access_token}"
+    if request_id:
+        # Correlates this pod-side call with the control-plane request it
+        # triggers — both sides stamp the same id as `trace.trace_id` on their
+        # `runtime.stage_latency_ms{runtime_stage=runtime_binding*}` event
+        # (TURN-01 evidence gap: no way to join a turn to its binding call
+        # besides timestamps).
+        headers["X-Request-Id"] = request_id
+    response = await http_client.get(url, headers=headers or None)
     if response.status_code == status.HTTP_404_NOT_FOUND:
         raise HTTPException(
             status_code=404, detail=response.text or "Unknown agent instance."
@@ -1260,12 +1354,13 @@ async def _authorize_execution_or_raise(
     - security disabled (no authenticated user) → skip (dev/local).
     - ReBAC engine absent or disabled (Noop) → skip (identity-only dev posture);
       the C3 profile guarantees an enabled engine in classified deployments.
-    - a personal space (`personal-<uid>`) is intrinsic ownership, not a stored
-      OpenFGA tuple: a human caller acting on their own canonical
-      `personal_team_id(authenticated_user.uid)` is authorized without an OpenFGA
-      call; any other `personal-*` id (another user's space, or the bare
-      `"personal"` alias) is explicitly denied — never routed to OpenFGA (AUTHZ-05
-      item 8b watch item).
+    - a personal space (`personal-<uid>`) is a real ReBAC team object (AUTHZ-08):
+      the owner's `team_editor` tuple self-heals on first touch inside
+      `RebacEngine.check_user_team_permission_or_raise`, and `add_relation`'s
+      write-guard refuses any tuple naming a personal team except that one, so
+      the plain `CAN_READ` check below already authorizes the owner and denies
+      everyone else (another user's space, or the bare `"personal"` alias, for
+      which no tuple is ever provisioned) — no special-casing needed here.
     - otherwise require the caller to hold `CAN_READ` on the requested team — the
       same relation the control-plane required before it would mint a grant. The
       team is caller-supplied but safe: OpenFGA only authorizes teams the user
@@ -1341,36 +1436,14 @@ async def _authorize_execution_or_raise(
             agent_instance_id=request.agent_instance_id,
         )
         return
-    if team_id == "personal" or is_personal_team_id(team_id):
-        # Personal spaces are intrinsic ownership (AUTHZ-05 item 8b): the id is
-        # derived from the JWT subject via `personal_team_id`, is never persisted
-        # as an OpenFGA tuple, and must never be resolved by OpenFGA. Only an
-        # exact match against the caller's own canonical id is authorized; any
-        # other personal-* id (another user's space) or the bare "personal"
-        # alias (ambiguous once ReBAC is active) is denied here, before OpenFGA
-        # ever sees it.
-        if team_id == personal_team_id(authenticated_user.uid):
-            _emit_audit_event(
-                container,
-                "info",
-                "personal_space_owner_authorized",
-                user_id=authenticated_user.uid,
-                team_id=team_id,
-                agent_instance_id=request.agent_instance_id,
-            )
-            return
-        _emit_audit_event(
-            container,
-            "warning",
-            "personal_space_denied",
-            user_id=authenticated_user.uid,
-            team_id=team_id,
-            agent_instance_id=request.agent_instance_id,
-        )
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail=f"user {authenticated_user.uid!r} is not authorized for team {team_id!r}",
-        )
+    # Personal spaces (AUTHZ-08, supersedes AUTHZ-05 item 8b) are now real
+    # ReBAC team objects: `RebacEngine.check_user_team_permission_or_raise`
+    # self-heals the owner's own `team_editor` tuple on first touch and
+    # `add_relation`'s write-guard refuses any other shape naming a personal
+    # team, so the bare `check_user_team_permission_or_raise` call below
+    # already authorizes the owner and denies everyone else — no special-
+    # casing needed here (the bare "personal" alias also denies normally,
+    # since no tuple is ever provisioned for that literal string).
     try:
         await rebac.check_user_team_permission_or_raise(
             authenticated_user, TeamPermission.CAN_READ, team_id
@@ -1506,15 +1579,34 @@ async def _authorize_and_resolve(
         )
     await _validate_session_checkpoint_access(request)
     await _enforce_session_ownership(request, authenticated_user, container)
-    await _authorize_execution_or_raise(request, authenticated_user, container)
+    async with runtime_stage_timer(container.get_kpi_writer(), "pod_authz"):
+        await _authorize_execution_or_raise(request, authenticated_user, container)
     internal_req = _to_internal_request(request)
-    target = await _resolve_agent_instance(
-        request=internal_req,
-        registry=registry,
-        access_token=access_token,
-        control_plane_url=get_runtime_context().config.control_plane_url,
-        team_id=request.effective_team_id(),
-    )
+    # Stamp the trusted service-agent verdict (never the caller-supplied
+    # context) so per-tool-call re-authorization can mirror the bypass
+    # `_authorize_execution_or_raise` already granted above (RFC EVAL-AUTH,
+    # Solution A) instead of re-running a ReBAC check this identity was
+    # never meant to satisfy. Overwritten unconditionally, both ways, so a
+    # caller can't spoof it via a body-supplied `context.is_service_agent`.
+    ctx = dict(internal_req.context or {})
+    if authenticated_user is not None and is_service_agent(authenticated_user):
+        ctx["is_service_agent"] = "true"
+    else:
+        ctx.pop("is_service_agent", None)
+    internal_req.context = ctx
+    binding_request_id = str(uuid4())
+    async with runtime_stage_timer(
+        container.get_kpi_writer(), "runtime_binding", trace_id=binding_request_id
+    ):
+        target = await _resolve_agent_instance(
+            request=internal_req,
+            registry=registry,
+            access_token=access_token,
+            control_plane_url=get_runtime_context().config.control_plane_url,
+            http_client=container.get_control_plane_http_client(),
+            team_id=request.effective_team_id(),
+            request_id=binding_request_id,
+        )
     _validate_resolved_team(request, target.team_id, container)
     return internal_req, target
 
@@ -1757,6 +1849,7 @@ async def _write_turn_history(
                     call_id=payload["call_id"],
                     content=payload.get("content", ""),
                     ok=not payload.get("is_error", False),
+                    latency_ms=payload.get("latency_ms"),
                 )
             )
             rank += 1
@@ -2163,6 +2256,7 @@ def _build_capability_save_services(
     user_id: str,
     team_id: str | None,
     access_token: str | None,
+    agent_instance_id: str | None = None,
 ) -> RuntimeServices:
     """
     Minimal `RuntimeServices` for one capability save-time validation (#1974).
@@ -2170,8 +2264,11 @@ def _build_capability_save_services(
     Why this exists:
     - `validate_config` may store uploaded asset binaries through the KF-backed
       workspace port and keep only the storage keys in the stored config
-      (RFC §3.4, §3.8) — so the save path needs `workspace_fs`, bound to the
-      saving user's identity/team, but none of the execution-only services
+      (RFC §3.4, §3.8) — so the save path needs `workspace_fs` plus the
+      per-instance `agent_assets` store (#1903), bound to the saving user's
+      identity/team, but none of the execution-only services
+    - `document_folders` lets an asset-parsing capability resolve author folder
+      strings against the agent's space at save time (#1903 image support)
     """
 
     request_id = str(uuid4())
@@ -2181,6 +2278,7 @@ def _build_capability_save_services(
             user_id=user_id,
             team_id=team_id,
             access_token=access_token,
+            agent_instance_id=agent_instance_id,
         ),
         portable_context=PortableContext(
             request_id=request_id,
@@ -2196,7 +2294,9 @@ def _build_capability_save_services(
     )
     settings = _PodAgentSettings(id=actor, name=actor, team_id=team_id, tuning=None)
     return RuntimeServices(
-        workspace_fs=FredWorkspaceFs(binding=binding, settings=settings)
+        workspace_fs=FredWorkspaceFs(binding=binding, settings=settings),
+        agent_assets=AgentConfigAssetsAdapter(binding=binding, settings=settings),
+        document_folders=DocumentFolderAdapter(binding=binding, settings=settings),
     )
 
 
@@ -2223,13 +2323,11 @@ def _effective_capability_ids(
     `default_mcp_servers` ids; a selected id that is a known-but-DISABLED
     catalog MCP server is dropped (the live tool provider skips it anyway —
     #1988 keeps that tolerance), while an id the pod knows nothing about stays
-    and fails loudly downstream. Non-ReAct templates carry no capabilities.
-    When the registry is absent the raw selection is returned unfiltered — the
-    caller decides whether that is an error.
+    and fails loudly downstream. Resolved identically for ReAct and Graph
+    agents. When the registry is absent the raw selection is returned
+    unfiltered — the caller decides whether that is an error.
     """
 
-    if not isinstance(definition, ReActAgentDefinition):
-        return []
     selected = tuning.selected_capability_ids if tuning is not None else None
     if selected is None:
         selected = [ref.id for ref in definition.default_mcp_servers]
@@ -2322,23 +2420,20 @@ def _build_capability_block(
     Returns None when the agent selects no capabilities.
 
     MCP handling (#1978, #1988): an MCP-server capability delivers its catalog
-    `agent_instructions` as a prompt fragment. The effective selection mirrors
+    `agent_instructions` as a prompt fragment via `middleware()`
+    (`_McpInstructionsMiddleware`). The effective selection mirrors
     `_active_mcp_server_refs`: a `None` capability selection (template default)
     activates the template's `default_mcp_servers` as capabilities so their
-    instructions are delivered — otherwise a default-configured agent would
-    silently lose its non-negotiable grounding contract.
+    instructions are delivered — otherwise a default ReAct agent would silently
+    lose its non-negotiable grounding contract. This block is built identically
+    for both agent kinds (CAPAB-02), but a Graph agent reads only `block.tools`
+    — MCP tools reach it (a separate, already execution-model-agnostic path,
+    `FredMcpToolProvider`), the `agent_instructions` prompt fragment does NOT
+    (Graph never reads `block.middleware` at all). A Graph agent that needs an
+    MCP server's grounding instructions must currently author them into its own
+    system prompt — this is an explicit, known gap, not yet closed (CAPAB-02).
     """
 
-    if not isinstance(definition, ReActAgentDefinition):
-        # Capabilities (incl. MCP instruction fragments) are ReAct-only (RFC §5).
-        # A non-ReAct template selecting real capabilities is still a loud error.
-        if tuning is not None and tuning.selected_capability_ids:
-            raise CapabilityError(
-                "Capabilities are only supported on ReAct agents (RFC §5); "
-                f"template '{definition.agent_id}' is not one."
-            )
-        return None
-
     selected = tuning.selected_capability_ids if tuning is not None else None
     capability_config = tuning.capability_config if tuning is not None else {}
     if capability_registry is None:
@@ -2359,6 +2454,49 @@ def _build_capability_block(
     effective = _effective_capability_ids(tuning, definition, capability_registry)
     if not effective:
         return None
+    if isinstance(definition, GraphAgentDefinition):
+        # CAPAB-02: a capability can declare itself ReAct-only
+        # (`CapabilityManifest.execution_models`) when its runtime need is a
+        # `middleware()` hook `tools()` cannot express (e.g. PPT filler's
+        # dynamic per-turn tool schema). Selecting one on a Graph agent must
+        # fail loudly here — never silently contribute zero tools (RFC §3.9
+        # "never silently degrade").
+        react_only = [
+            cap_id
+            for cap_id in effective
+            if cap_id in capability_registry
+            and "graph"
+            not in capability_registry.capability(cap_id).manifest.execution_models
+        ]
+        if react_only:
+            raise CapabilityError(
+                f"Agent selects capabilities {react_only} which are ReAct-only "
+                "(CapabilityManifest.execution_models) and cannot run on a "
+                "Graph agent."
+            )
+        # CAPAB-02 stopgap: `CapabilityAgentBlock.hitl` is built (assembly.py)
+        # but `GraphRuntime.invoke_runtime_tool` never consults it — a
+        # capability's `HitlSpec` gates a ReAct tool call but not a Graph
+        # one. No production capability declares an active `HitlSpec` today,
+        # so refusing here costs nothing real yet; reconciling Graph's own
+        # node-level pause/resume with the per-tool HITL gate is real design
+        # work, deferred (see AGENT-CAPABILITY-RFC.md §3.9). Refusing loudly
+        # keeps the RFC's "never silently degrade" guarantee intact in the meantime
+        # — a capability with `HitlSpec`s that silently ran ungated on Graph
+        # would be exactly the kind of governance gap this platform exists to
+        # prevent.
+        hitl_gated = [
+            cap_id
+            for cap_id in effective
+            if cap_id in capability_registry
+            and capability_registry.capability(cap_id).hitl_specs()
+        ]
+        if hitl_gated:
+            raise CapabilityError(
+                f"Agent selects capabilities {hitl_gated} which declare "
+                "HitlSpec approval gates; Graph agents do not yet enforce "
+                "capability HITL (CAPAB-02) and cannot run them."
+            )
     contexts = build_capability_contexts(
         capability_registry,
         selected_capability_ids=effective,
@@ -2413,6 +2551,19 @@ async def _iterate_runtime_event_payloads(
     ctx = request.context or {}
     correlation_id = ctx.get("correlation_id", request_id)
     resolved_team_id = team_id or ctx.get("team_id")
+    # kind="model" enforcement (OBSERV-02 v3, AGENT-CAPABILITY-RFC.md §8.7):
+    # computed ONCE per turn, here — never inside model-routing resolution,
+    # which runs multiple times per turn and must never itself make a ReBAC
+    # call. No team context (agent-to-agent invocation) → no restriction,
+    # the same posture _authorize_execution_or_raise already applies to a
+    # teamless request.
+    usable_model_ids: tuple[str, ...] | None = None
+    if resolved_team_id is not None:
+        from ..model_routing import usable_model_capability_ids
+
+        rebac = get_runtime_context().config.rebac_engine
+        ids = await usable_model_capability_ids(rebac, resolved_team_id)
+        usable_model_ids = tuple(ids) if ids is not None else None
     execution_action = ctx.get("execution_action") or (
         ExecutionGrantAction.RESUME.value
         if request.resume_payload is not None
@@ -2440,6 +2591,7 @@ async def _iterate_runtime_event_payloads(
                 "checkpoint_id": resolved_checkpoint_id,
                 "execution_action": execution_action,
                 "exchange_id": exchange_id,
+                "is_service_agent": ctx.get("is_service_agent"),
             }.items()
             if isinstance(value, str) and value
         },
@@ -2480,11 +2632,26 @@ async def _iterate_runtime_event_payloads(
         # When the final file is deleted this is absent, so the per-turn runtime
         # notice disappears without leaving a checkpointed system message behind.
         attachments_markdown=ctx.get("attachments_markdown"),
+        # Team routing policy snapshot (TEAM-ROUTING-POLICY-RFC.md §3/§8):
+        # control-plane resolves it once at prepare-execution and the frontend
+        # forwards it unchanged, same channel as context_prompt_text above — but
+        # it was also silently dropped here, so resolve_team_override in
+        # fred_runtime.model_routing.provider always saw None and no team's
+        # routing policy ever took effect on a real chat turn. ctx already holds
+        # the flat dict from to_legacy_context()'s model_dump(exclude_none=True);
+        # operation_route_rules needs re-validating back into typed rows.
+        chat_default_profile_id=ctx.get("chat_default_profile_id"),
+        operation_route_rules=[
+            TeamOperationRouteRule.model_validate(rule)
+            for rule in (ctx.get("operation_route_rules") or [])
+        ]
+        or None,
     )
 
     binding = BoundRuntimeContext(
         runtime_context=runtime_context,
         portable_context=portable_context,
+        usable_model_ids=usable_model_ids,
     )
 
     services = _build_runtime_services(
@@ -2540,6 +2707,7 @@ async def _iterate_runtime_event_payloads(
             runtime = GraphRuntime(
                 definition=definition,
                 services=services,
+                capability_block=capability_block,
             )
             runtime.bind(binding)
             await runtime.activate()
@@ -2806,7 +2974,7 @@ def _build_agent_router(
         """
 
         capability_registry = _capability_registry_of(http_request)
-        available_capabilities = (
+        all_capability_entries = (
             [
                 CapabilityCatalogEntry.from_manifest(
                     capability_registry.capability(cap_id).manifest,
@@ -2826,7 +2994,21 @@ def _build_agent_router(
                 kind=definition.execution_category,
                 default_tuning=_definition_to_agent_tuning(definition),
                 available_mcp_servers=_available_mcp_servers_for_definition(definition),
-                available_capabilities=available_capabilities,
+                # CAPAB-02: a capability declared `execution_models=("react",)`
+                # must not even be offered for selection on a Graph template —
+                # `_build_capability_block` would refuse it loudly at save/run
+                # time regardless, but a picker that lists it first invites the
+                # exact "select it, save it, discover the incompatibility at
+                # first launch" flow the loud refusal exists to prevent.
+                available_capabilities=(
+                    all_capability_entries
+                    if not isinstance(definition, GraphAgentDefinition)
+                    else [
+                        entry
+                        for entry in all_capability_entries
+                        if "graph" in entry.execution_models
+                    ]
+                ),
                 default_capability_ids=[
                     ref.id for ref in definition.default_mcp_servers
                 ],
@@ -2869,6 +3051,42 @@ def _build_agent_router(
             ]
         )
 
+    @router.get("/models-catalog")
+    async def get_models_catalog() -> _ModelCatalogResponse:
+        """
+        Return this pod's routable models, one entry per distinct
+        (provider, name) pair (OBSERV-02 v3, `AGENT-CAPABILITY-RFC.md` §8.7).
+
+        Why this endpoint exists:
+        - control-plane's capability catalog aggregation
+          (`aggregate_capability_catalog`) has no other way to learn what
+          models this pod can route to — `models_catalog.yaml` is loaded
+          only here, for routing, with no prior control-plane consumer.
+        - one entry per (provider, name), not per catalog profile: a model
+          used for both the `chat` and `language` routing capability is one
+          admin enablement decision, not two.
+
+        Re-reads `models_catalog.yaml` fresh on every call (same file
+        `_build_chat_model_factory` loaded once at boot) rather than
+        caching the parsed catalog — this route is polled rarely (admin
+        catalog refresh), never per-turn, so the extra local file read is
+        immaterial and keeps this always consistent with whatever the pod
+        would actually resolve, with no separate cache to go stale.
+
+        How to use it:
+        - call from control-plane's `_model_capabilities_for_source`
+
+        Example:
+        - `GET /fred/agents/v2/agents/models-catalog`
+        """
+        from ..model_routing import load_model_catalog
+
+        catalog_path = get_runtime_context().config.models_catalog_path
+        if not catalog_path:
+            return _ModelCatalogResponse(models=[])
+        catalog = load_model_catalog(catalog_path)
+        return _ModelCatalogResponse(models=_project_model_catalog_entries(catalog))
+
     @router.post("/capabilities/{capability_id}/validate-config")
     async def validate_capability_config(
         capability_id: str,
@@ -2979,6 +3197,10 @@ def _build_agent_router(
                 user_id=(caller.uid if caller is not None else None) or "anonymous",
                 team_id=team_id or None,
                 access_token=access_token,
+                agent_instance_id=(
+                    form_instance_id if isinstance(form_instance_id, str) else None
+                )
+                or None,
             ),
         )
         try:
@@ -3806,12 +4028,13 @@ def create_agent_app(
         # Boot order (must be preserved — each step depends on the previous):
         # 1. log_setup         — formatter/handlers ready for all subsequent logs
         # 2. initialize_kpi_writer — needed by bootstrap_observability
-        # 3. bootstrap_observability — global tracer + metrics provider
-        # 4. attach_pod_container — container in app.state before any request
-        # 5. initialize_sql    — async, may take time
-        # 6. start_metrics_exporter — prometheus thread, after KPI writer exists
-        # 7. start_kpi_tasks   — asyncio tasks, after SQL engine is known
-        # 8. set_runtime_context — wires all built parts into the global config
+        # 3. initialize_control_plane_client — sync, no network until first call
+        # 4. bootstrap_observability — global tracer + metrics provider
+        # 5. attach_pod_container — container in app.state before any request
+        # 6. initialize_sql    — async, may take time
+        # 7. start_metrics_exporter — prometheus thread, after KPI writer exists
+        # 8. start_kpi_tasks   — asyncio tasks, after SQL engine is known
+        # 9. set_runtime_context — wires all built parts into the global config
         log_setup(
             service_name=config.app.name,
             log_level=config.app.log_level,
@@ -3822,6 +4045,7 @@ def create_agent_app(
         )
         container = build_pod_container(config)
         container.initialize_kpi_writer()
+        container.initialize_control_plane_client()
         bootstrap_observability(
             config.observability, kpi_writer=container.get_kpi_writer()
         )
@@ -3839,7 +4063,11 @@ def create_agent_app(
         # every execution against OpenFGA; a disabled/Noop engine (dev) means
         # identity-only. Safe in all modes — the factory returns a Noop with a
         # KeycloackDisabled admin client when user/m2m auth is off.
-        rebac_engine = rebac_factory(security) if security is not None else None
+        rebac_engine = (
+            rebac_factory(security, kpi_writer=container.get_kpi_writer())
+            if security is not None
+            else None
+        )
         chat_factory = _build_chat_model_factory(config)
         await container.initialize_sql()
         container.start_metrics_exporter()
@@ -3860,6 +4088,7 @@ def create_agent_app(
                     checkpointer=checkpointer,
                     history_store=history_store,
                     mcp_configuration=config.get_mcp_configuration(),
+                    models_catalog_path=config.get_models_catalog_path(),
                     inprocess_toolkit_factory=build_inprocess_toolkit,
                     control_plane_url=config.platform.control_plane_url,
                     rebac_engine=rebac_engine,