fred-runtime 3.3.7__tar.gz → 3.4.1__tar.gz

{fred_runtime-3.3.7 → fred_runtime-3.4.1}/PKG-INFO

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

{fred_runtime-3.3.7 → fred_runtime-3.4.1}/fred_runtime/app/agent_app.py

@@ -56,8 +56,10 @@ 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.diagnostics import install_gc_diagnostics
 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
@@ -88,6 +90,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 (
@@ -791,6 +794,7 @@ def _build_runtime_services(
     return RuntimeServices(
         tracer=build_default_tracer(),
         metrics=KPIWriterMetricsAdapter(runtime_config.kpi_writer),
+        kpi_writer=runtime_config.kpi_writer,
         chat_model_factory=runtime_config.chat_model_factory,
         tool_invoker=tool_invoker,
         tool_provider=tool_provider,
@@ -967,6 +971,84 @@ 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."""
+    thinking_profile_ids: list[str] = Field(default_factory=list)
+    """The subset of `profile_ids` above declaring `supports_thinking`
+    (`MODEL-REASONING-ENABLEMENT-RFC.md` §5.3, REASON-01). DERIVED here,
+    never authored twice: aptitude is declared per profile (§4, where the
+    behaviour actually differs), while the admin toggle is keyed per model
+    because that is what the capability id space and the admin UI both are
+    (§5.2 — the id space is not negotiable). This field is the projection
+    between the two.
+
+    Empty means this model has NO reasoning-capable profile, and the admin row
+    shows no reasoning control at all — aptitude is not a choice, an
+    administrator cannot make a model reason. Non-empty means the row carries
+    the toggle. Same established join as `profile_ids` above."""
+
+
+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:
+            existing = _ModelCatalogEntry(
+                id=model_capability_id(provider, name),
+                provider=provider,
+                name=name,
+                description=profile.description,
+                profile_ids=[profile.profile_id],
+            )
+            seen[key] = existing
+        else:
+            existing.profile_ids.append(profile.profile_id)
+        # REASON-01 §5.3: aptitude is per profile, the toggle is per model —
+        # this one condition is the whole projection between them.
+        if profile.supports_thinking:
+            existing.thinking_profile_ids.append(profile.profile_id)
+    return list(seen.values())
+
+
 class _ResolvedAgentInstance(BaseModel):
     agent_instance_id: str
     template_agent_id: str
@@ -1120,7 +1202,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.
@@ -1195,9 +1279,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."
@@ -1286,12 +1378,21 @@ async def _authorize_execution_or_raise(
       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
+      the `CAN_USE_TEAM_AGENTS` check below already authorizes the owner
+      (`team_editor` implies `team_member`) 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_USE_TEAM_AGENTS` on the
+      requested team — `team_member`-only, unlike `CAN_READ` (which also
+      admits the `public` marketplace-discovery relation, TEAM-09/TEAM-10).
+      Execution is real content access, not discovery, so a public-team
+      visitor must not pass here even though they can see the team profile.
+      This used to check `CAN_READ` (the same relation the control-plane
+      required before it would mint a grant) — that predates TEAM-09's
+      `public` relation and was never revisited; `product/api.py`'s
+      `post_prepare_execution` made the identical correction for the same
+      reason (returns prompt content, not just config). The team is
+      caller-supplied but safe: OpenFGA only authorizes teams the user
       actually holds a relation to. Authorization and denial are both audited;
       any OpenFGA denial fails closed (403).
 
@@ -1374,7 +1475,7 @@ async def _authorize_execution_or_raise(
     # 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
+            authenticated_user, TeamPermission.CAN_USE_TEAM_AGENTS, team_id
         )
     except AuthorizationError as exc:
         _emit_audit_event(
@@ -1507,7 +1608,8 @@ 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)
     # Stamp the trusted service-agent verdict (never the caller-supplied
     # context) so per-tool-call re-authorization can mirror the bypass
@@ -1521,13 +1623,19 @@ async def _authorize_and_resolve(
     else:
         ctx.pop("is_service_agent", None)
     internal_req.context = ctx
-    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(),
-    )
+    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
 
@@ -1651,6 +1759,27 @@ async def _validate_session_checkpoint_access(
         )
 
 
+@dataclass
+class _OpenThought:
+    """
+    One reasoning block being accumulated while mapping a turn to history rows.
+
+    Why the rank is reserved at THOUGHT_START rather than at THOUGHT_END:
+    - a model-native block opens on the first reasoning token and closes only at
+      the first answer delta (RFC AGENT-THINKING-API §7.3), so it brackets every
+      tool call of the turn
+    - the live UI assigns the row's rank at `thought_start` (`useChatSse.ts`);
+      ranking it at close instead would file the reasoning *after* the tools it
+      actually preceded, so a reloaded trace would not match what the user saw
+    """
+
+    rank: int
+    phase: str
+    title: str | None
+    source: str | None
+    text: list[str] = field(default_factory=list)
+
+
 async def _write_turn_history(
     *,
     session_id: str,
@@ -1686,6 +1815,7 @@ async def _write_turn_history(
     Event-to-message mapping:
     - ``tool_call``      → ``Role.assistant / Channel.tool_call``
     - ``tool_result``    → ``Role.tool    / Channel.tool_result``
+    - ``thought_*``      → ``Role.assistant / Channel.thought`` (one row per block)
     - ``awaiting_human`` → ``Role.system  / Channel.hitl_request`` (full choices)
     - ``node_error``     → ``Role.system  / Channel.error``
     - ``final``          → ``Role.assistant / Channel.final`` (answer + sources)
@@ -1695,6 +1825,7 @@ async def _write_turn_history(
     from fred_core.history.history_schema import (
         Channel,
         ChatMessage,
+        ChatMetadata,
         ChatTokenUsage,
         Role,
         TextPart,
@@ -1738,6 +1869,55 @@ async def _write_turn_history(
         messages.append(make_user_text(session_id, exchange_id, rank, request_message))
         rank += 1
 
+    # Reasoning blocks still accumulating, keyed by thought_id. A block reserves
+    # its rank when it opens but only becomes a row once its text is complete.
+    open_thoughts: dict[str, _OpenThought] = {}
+
+    def _thought_row(
+        block: _OpenThought,
+        *,
+        thought_id: str,
+        conclusion: str | None = None,
+        duration_ms: int | None = None,
+    ) -> ChatMessage:
+        """
+        Build one ``Channel.thought`` row from an accumulated reasoning block.
+
+        The envelope must match what the live stream emits client-side
+        (`useChatSse.ts`) — same role, same channel, same ``metadata.extras``
+        keys — because the chat UI feeds streamed and reloaded messages through
+        a single rendering path (`traceUtils.thoughtExtras`).
+
+        ``streaming_delta`` is deliberately absent: a persisted block is
+        complete, and carrying that flag would render it as still running.
+        """
+        return ChatMessage(
+            session_id=session_id,
+            exchange_id=exchange_id,
+            rank=block.rank,
+            timestamp=datetime.now(timezone.utc),
+            role=Role.assistant,
+            channel=Channel.thought,
+            parts=[TextPart(text="".join(block.text))],
+            # `extras` is not a declared field: `ChatMetadata` sets
+            # `extra="allow"` precisely so callers can attach structured payloads
+            # without every consumer of the model growing a dependency on them.
+            # `model_validate` is how that is reached type-safely — a keyword
+            # argument would not type-check against the declared fields.
+            metadata=ChatMetadata.model_validate(
+                {
+                    "extras": {
+                        "thought_id": thought_id,
+                        "phase": block.phase,
+                        "title": block.title,
+                        "source": block.source,
+                        "conclusion": conclusion,
+                        "duration_ms": duration_ms,
+                    }
+                }
+            ),
+        )
+
     # 2. Map runtime events to messages
     final_content = ""
     final_sources: list[VectorSearchHit] = []
@@ -1775,6 +1955,48 @@ async def _write_turn_history(
             )
             rank += 1
 
+        elif kind == "thought_start":
+            # `tool_use` blocks are synthetic bookkeeping the runtime opens around
+            # every tool call (RFC Amendment A, Layer 1). The chat UI has hidden
+            # them since Amendment B — the tool call/result combo row already
+            # carries what ran, how it went and how long it took. Persisting them
+            # would file up to `max_tool_calls_per_turn` content-free rows a turn.
+            if payload.get("phase") == "tool_use":
+                continue
+            thought_id = str(payload.get("thought_id") or "")
+            if not thought_id:
+                continue
+            open_thoughts[thought_id] = _OpenThought(
+                rank=rank,
+                phase=str(payload.get("phase") or "planning"),
+                title=payload.get("title"),
+                source=payload.get("source"),
+            )
+            rank += 1
+
+        elif kind == "thought_delta":
+            block = open_thoughts.get(str(payload.get("thought_id") or ""))
+            if block is not None:
+                block.text.append(str(payload.get("delta") or ""))
+
+        elif kind == "thought_end":
+            thought_id = str(payload.get("thought_id") or "")
+            block = open_thoughts.pop(thought_id, None)
+            # A block with neither text nor conclusion carries nothing to show;
+            # persisting it would render an empty reasoning card on reload. Its
+            # reserved rank is simply left unused — ranks must increase, not be
+            # contiguous.
+            conclusion = payload.get("conclusion")
+            if block is not None and ("".join(block.text) or conclusion):
+                messages.append(
+                    _thought_row(
+                        block,
+                        thought_id=thought_id,
+                        conclusion=conclusion,
+                        duration_ms=payload.get("duration_ms"),
+                    )
+                )
+
         elif kind == "awaiting_human":
             # Store the full HITL gate definition — question and all choices —
             # so audit logs and UI replay have the complete structured record.
@@ -1833,6 +2055,14 @@ async def _write_turn_history(
             final_model = payload.get("model_name")
             final_finish_reason = payload.get("finish_reason")
 
+    # 2b. Blocks the stream never closed (truncated turn, crashed node). The live
+    # UI closes them itself on `final` so the accordion does not pulse forever
+    # (`useChatSse.ts`); history keeps the same parity — reasoning the user was
+    # shown must not disappear on reload just because the block was left open.
+    for thought_id, block in open_thoughts.items():
+        if "".join(block.text):
+            messages.append(_thought_row(block, thought_id=thought_id))
+
     # 3. Terminal assistant message (from FinalRuntimeEvent)
     if final_content or final_model:
         messages.append(
@@ -2401,8 +2631,8 @@ def _build_capability_block(
         # 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 (id-legend.yaml CAPAB-02). Refusing loudly keeps the
-        # RFC §3.9 "never silently degrade" guarantee intact in the meantime
+        # 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.
@@ -2472,6 +2702,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
@@ -2540,11 +2783,55 @@ 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,
+        # Platform reasoning activation snapshot (REASON-01,
+        # `MODEL-REASONING-ENABLEMENT-RFC.md` §5.5) — same channel and same
+        # session-prep lifecycle as the two fields above, and forwarded here
+        # for the same hard-won reason: this mapping is field-by-field, so a
+        # field that is not named is silently dropped. Both comments above
+        # record a production bug caused by exactly that. `RoutedChatModelFactory`
+        # strips the reasoning settings for every model absent from this list
+        # (§5.6.2), so dropping it here would pin reasoning permanently OFF and
+        # make the admin toggle decorative — the failure §5.6.2 exists to
+        # prevent, one layer up from where it is enforced.
+        #
+        # Intersected with level 3 (the agent's own switch) rather than taken
+        # as-is, and that is the whole point of doing it HERE: this list rides
+        # the request, `tuning` is resolved server-side from the managed
+        # instance. An agent whose author did not enable reasoning must not
+        # reason whatever the request claims the platform allows — all four
+        # levels must hold (§3), so the ceiling is `level 2 AND level 3`.
+        # Absent tuning (agent-to-agent invocation, no managed instance) means
+        # no author ever enabled it: off, the default everywhere in REASON-01.
+        reasoning_enabled_model_ids=(
+            ctx.get("reasoning_enabled_model_ids")
+            if tuning is not None and tuning.reasoning_enabled
+            else []
+        ),
+        # The user's per-question reasoning choice (REASON-01 level 4). Same
+        # trap as every field above: unnamed here means silently dropped. Kept
+        # tri-state on purpose — `ctx.get` yielding None means "the agent never
+        # offered the choice", which is NOT the same as the user answering no.
+        reasoning=ctx.get("reasoning"),
     )
 
     binding = BoundRuntimeContext(
         runtime_context=runtime_context,
         portable_context=portable_context,
+        usable_model_ids=usable_model_ids,
     )
 
     services = _build_runtime_services(
@@ -2944,6 +3231,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,
@@ -3884,13 +4207,19 @@ def create_agent_app(
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:
         # 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
+        # 2. install_gc_diagnostics — independent of everything below; installed
+        #    early so SIGUSR1/SIGUSR2 (fred_core.diagnostics) are live for the
+        #    pod's whole lifetime, protecting every agent pod (ours and third
+        #    parties' alike) against the reference-cycle class of leak found in
+        #    ISSUE-010 without any per-pod code
+        # 3. initialize_kpi_writer — needed by bootstrap_observability
+        # 4. initialize_control_plane_client — sync, no network until first call
+        # 5. bootstrap_observability — global tracer + metrics provider
+        # 6. attach_pod_container — container in app.state before any request
+        # 7. initialize_sql    — async, may take time
+        # 8. start_metrics_exporter — prometheus thread, after KPI writer exists
+        # 9. start_kpi_tasks   — asyncio tasks, after SQL engine is known
+        # 10. set_runtime_context — wires all built parts into the global config
         log_setup(
             service_name=config.app.name,
             log_level=config.app.log_level,
@@ -3899,8 +4228,10 @@ def create_agent_app(
                 opensearch_config=config.storage.opensearch,
             ),
         )
+        gc_diagnostics = install_gc_diagnostics()
         container = build_pod_container(config)
         container.initialize_kpi_writer()
+        container.initialize_control_plane_client()
         bootstrap_observability(
             config.observability, kpi_writer=container.get_kpi_writer()
         )
@@ -3918,7 +4249,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()
@@ -3939,6 +4274,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,
@@ -3961,6 +4297,7 @@ def create_agent_app(
             list(registry.keys()),
         )
         yield
+        await gc_diagnostics.stop()
         await container.shutdown()
 
     app = FastAPI(