Inform AI engine which endpoints are disabled on the backend (#6251)

# Description of Changes
Have the Java send a list of enabled endpoints to the AI engine so it
can intelligently respond to the user that the tool does exist but is
disabled on the server so it can't acutally run the operation, instead
of the current behaviour where it sends the API call back and then 503
errors because the execution fails when the URL is disabled.

<img width="380" height="208" alt="image"
src="https://github.com/user-attachments/assets/5842fb2e-2e55-45a5-8205-25515636daae"
/>

---------

Co-authored-by: EthanHealy01 <[email protected]>

engine/src/stirling/agents/pdf_edit.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Iterable
 from typing import Literal, overload
 
 from pydantic import Field
@@ -140,7 +141,6 @@ class PdfEditParameterSelector:
 class PdfEditAgent:
     def __init__(self, runtime: AppRuntime) -> None:
         self.runtime = runtime
-        self.supported_operations = list(OPERATIONS)
         self.parameter_selector = PdfEditParameterSelector(runtime)
 
     async def orchestrate(self, request: OrchestratorRequest) -> PdfEditResponse:
@@ -156,6 +156,7 @@ class PdfEditAgent:
                 files=request.files,
                 conversation_history=request.conversation_history,
                 page_text=extracted_text.files if extracted_text is not None else [],
+                enabled_endpoints=request.enabled_endpoints,
             )
         )
 
@@ -165,19 +166,37 @@ class PdfEditAgent:
     async def handle(self, request: PdfEditRequest, allow_need_content: bool = True) -> PdfEditResponse: ...
     async def handle(self, request: PdfEditRequest, allow_need_content: bool = True) -> PdfEditResponse:
         logger.info(
-            "[pdf-edit] handle: files=%s has_text=%s allow_need_content=%s msg=%r",
+            "[pdf-edit] handle: files=%s has_text=%s allow_need_content=%s enabled=%s msg=%r",
             [file.name for file in request.files],
             has_page_text(request.page_text),
             allow_need_content,
+            request.enabled_endpoints,
             request.user_message,
         )
-        selection = await self._select_plan(request, allow_need_content=allow_need_content)
+        supported_operations = self._get_supported_operations(request)
+        unavailable_operations = self._get_unavailable_operations(supported_operations)
+        if not supported_operations:
+            return EditCannotDoResponse(reason="No PDF edit operations are available on this server.")
+        selection = await self._select_plan(
+            request, supported_operations, unavailable_operations, allow_need_content=allow_need_content
+        )
         if isinstance(selection, EditClarificationRequest | EditCannotDoResponse):
             logger.info("[pdf-edit] selection -> %s: %s", selection.outcome, Pretty(selection))
             return selection
         if isinstance(selection, NeedContentResponse):
             logger.info("[pdf-edit] selection -> need_content: %s", selection.reason)
             return self._fill_need_content_defaults(selection, request)
+        enabled = set(supported_operations)
+        unsupported = [op for op in selection.operations if op not in enabled]
+        if unsupported:
+            logger.warning("[pdf-edit] plan referenced unavailable operations: %s", [op.name for op in unsupported])
+            return EditCannotDoResponse(
+                reason=(
+                    "The following operations are not available on this server "
+                    "(either disabled by the administrator or not installed): "
+                    + ", ".join(op.name for op in unsupported)
+                )
+            )
         logger.info("[pdf-edit] plan: %s", [op.name for op in selection.operations])
         steps: list[ToolOperationStep] = []
         for operation_index, operation_id in enumerate(selection.operations):
@@ -202,18 +221,39 @@ class PdfEditAgent:
     async def _select_plan(
         self,
         request: PdfEditRequest,
+        supported_operations: Iterable[ToolEndpoint],
+        unavailable_operations: Iterable[ToolEndpoint],
+        *,
         allow_need_content: bool = True,
     ) -> PdfEditPlanOutput:
         can_request_content = allow_need_content and not has_page_text(request.page_text)
-        agent = self._build_selection_agent(allow_need_content=can_request_content)
-        return await agent.select(self._build_selection_prompt(request))
+        agent = self._build_selection_agent(
+            supported_operations, unavailable_operations, allow_need_content=can_request_content
+        )
+        return await agent.select(self._build_selection_prompt(request, supported_operations, unavailable_operations))
 
-    def _build_selection_agent(self, *, allow_need_content: bool) -> PdfEditSelectionAgent:
+    def _build_selection_agent(
+        self,
+        supported_operations: Iterable[ToolEndpoint],
+        unavailable_operations: Iterable[ToolEndpoint],
+        *,
+        allow_need_content: bool,
+    ) -> PdfEditSelectionAgent:
+        unavailable_clause = (
+            f" The following operations exist on this server but are NOT currently available "
+            f"(disabled by the administrator or not installed in this build) and must NOT appear "
+            f"in any plan: {self._get_operations_prompt(unavailable_operations)}. "
+            "If the user asks for one of these, return cannot_do, name the operation, and explain "
+            "that it exists but isn't available on this server."
+            if unavailable_operations
+            else ""
+        )
         return PdfEditSelectionAgent(
             self.runtime,
             base_system_prompt=(
                 "Plan PDF edit requests. "
-                f"Supported operations are: {self._supported_operations_prompt()}. "
+                f"Supported operations are: {self._get_operations_prompt(supported_operations)}."
+                f"{unavailable_clause} "
                 "Return an ordered list of one or more supported operations for the plan. "
                 "Do not produce operation parameters in this stage. "
                 "Return need_clarification when the request is genuinely ambiguous. "
@@ -224,17 +264,38 @@ class PdfEditAgent:
             allow_need_content=allow_need_content,
         )
 
-    def _build_selection_prompt(self, request: PdfEditRequest) -> str:
+    def _build_selection_prompt(
+        self,
+        request: PdfEditRequest,
+        supported_operations: Iterable[ToolEndpoint],
+        unavailable_operations: Iterable[ToolEndpoint],
+    ) -> str:
+        unavailable_line = (
+            "Unavailable operations (exist but not currently usable): "
+            f"{self._get_operations_prompt(unavailable_operations)}\n"
+            if unavailable_operations
+            else ""
+        )
         return (
             f"Conversation history:\n{format_conversation_history(request.conversation_history)}\n"
             f"User request: {request.user_message}\n"
             f"Files: {format_file_names(request.files)}\n"
-            f"Supported operations: {self._supported_operations_prompt()}\n"
+            f"Supported operations: {self._get_operations_prompt(supported_operations)}\n"
+            f"{unavailable_line}"
             f"Extracted page text:\n{format_page_text(request.page_text)}"
         )
 
-    def _supported_operations_prompt(self) -> str:
-        return ", ".join(f"{op.name} ({op.value})" for op in self.supported_operations)
+    def _get_supported_operations(self, request: PdfEditRequest) -> Iterable[ToolEndpoint]:
+        return request.enabled_endpoints
+
+    @staticmethod
+    def _get_unavailable_operations(supported_operations: Iterable[ToolEndpoint]) -> Iterable[ToolEndpoint]:
+        supported_set = set(supported_operations)
+        return [op for op in OPERATIONS if op not in supported_set]
+
+    @staticmethod
+    def _get_operations_prompt(operations: Iterable[ToolEndpoint]) -> str:
+        return ", ".join(f"{op.name} ({op.value})" for op in operations)
 
     def _fill_need_content_defaults(
         self,

engine/src/stirling/contracts/common.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Iterable
 from enum import StrEnum
 from typing import Literal, assert_never
 
@@ -197,3 +198,14 @@ class ToolOperationStep(ApiModel):
             actual_type = type(self.parameters).__name__
             raise ValueError(f"Parameters for tool {self.tool} must be {expected_type.__name__}, got {actual_type}.")
         return self
+
+
+def drop_unknown_tool_endpoints(value: Iterable[str | ToolEndpoint]) -> list[ToolEndpoint]:
+    """Coerce inbound endpoint identifiers into `ToolEndpoint` members, dropping unknowns.
+
+    Java sends the full set of endpoints it considers enabled. The engine and the Java
+    backend may have version drift in either direction, so we silently drop anything we
+    don't recognise rather than failing the request. Anything dropped simply doesn't
+    appear as a supported tool to the planner.
+    """
+    return [ToolEndpoint(item) for item in value if item in ToolEndpoint]

engine/src/stirling/contracts/orchestrator.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 from typing import Annotated, Literal
 
-from pydantic import Field
+from pydantic import BeforeValidator, Field
 
-from stirling.models import ApiModel
+from stirling.models import ApiModel, ToolEndpoint
 
 from .agent_drafts import AgentDraftResponse
 from .common import (
@@ -17,6 +17,7 @@ from .common import (
     SupportedCapability,
     ToolReportArtifact,
     WorkflowOutcome,
+    drop_unknown_tool_endpoints,
 )
 from .execution import NextExecutionAction
 from .pdf_edit import PdfEditTerminalResponse
@@ -37,6 +38,10 @@ class OrchestratorRequest(ApiModel):
     conversation_history: list[ConversationMessage] = Field(default_factory=list)
     artifacts: list[WorkflowArtifact] = Field(default_factory=list)
     resume_with: SupportedCapability | None = None
+    # See `PdfEditRequest.enabled_endpoints`.
+    enabled_endpoints: Annotated[list[ToolEndpoint], BeforeValidator(drop_unknown_tool_endpoints)] = Field(
+        default_factory=list
+    )
 
 
 class UnsupportedCapabilityResponse(ApiModel):

engine/src/stirling/contracts/pdf_edit.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 from typing import Annotated, Literal
 
-from pydantic import Field
+from pydantic import BeforeValidator, Field
 
-from stirling.models import ApiModel
+from stirling.models import ApiModel, ToolEndpoint
 
 from .common import (
     AiFile,
@@ -14,6 +14,7 @@ from .common import (
     SupportedCapability,
     ToolOperationStep,
     WorkflowOutcome,
+    drop_unknown_tool_endpoints,
 )
 
 
@@ -22,6 +23,13 @@ class PdfEditRequest(ApiModel):
     files: list[AiFile] = Field(default_factory=list)
     conversation_history: list[ConversationMessage] = Field(default_factory=list)
     page_text: list[ExtractedFileText] = Field(default_factory=list)
+    # The set of endpoints the Java backend considers usable. Unknown URLs are silently
+    # dropped so the engine and Java can drift in either direction without breaking
+    # validation. An empty list means no operations are available - the planner will
+    # return `cannot_do`.
+    enabled_endpoints: Annotated[list[ToolEndpoint], BeforeValidator(drop_unknown_tool_endpoints)] = Field(
+        default_factory=list
+    )
 
 
 class EditPlanResponse(ApiModel):