Improve consistency and reliability of tools in Stirling Engine (Stirling-Tools#6855)

# Description of Changes
A few changes to improve things in the engine:
- Changed the PDF to Markdown code to be a real tool in Java, to remove
the need for the `pdf_ingest` code, which looked a bit like an agent but
wasn't behaving as an agent. It's now just covered automatically by the
edit agent.
- Noticed that 0-parameter-endpoints were previously being ignored by
the `tool_models` generator, so some tools which require no params were
being mistakenly excluded.
- Removed tools which currently never succeed like Add Stamp, Cert Sign,
and Overlay, because they require the supporting files to be sent in a
different location in the API call, which we don't currently do.
Ideally, we'd add proper support for this, but we're better off now
removing support for these tools rather than just have them crash. We
can re-add these tools in a future PR properly.

Author: jbrunton96

app/proprietary/src/main/java/stirling/software/proprietary/model/api/ai/AiWorkflowOutcome.java

@@ -21,8 +21,7 @@ public enum AiWorkflowOutcome {
     COMPLETED("completed"),
     UNSUPPORTED_CAPABILITY("unsupported_capability"),
     CANNOT_CONTINUE("cannot_continue"),
-    GENERATE_FILE("generate_file"),
-    CONVERT_MARKDOWN("convert_markdown");
+    GENERATE_FILE("generate_file");
 
     private final String value;
 

app/proprietary/src/main/java/stirling/software/proprietary/service/AiWorkflowService.java

@@ -68,7 +68,6 @@
 public class AiWorkflowService {
 
     private static final String DOCUMENTS_ENDPOINT = "/api/v1/documents";
-    private static final String PDF_TO_MARKDOWN_ENDPOINT = "/api/v1/convert/pdf/markdown";
 
     private final CustomPDFDocumentFactory pdfDocumentFactory;
     private final AiEngineClient aiEngineClient;
@@ -196,7 +195,6 @@ private WorkflowState advance(
         return switch (response.getOutcome()) {
             case NEED_CONTENT -> onNeedContent(response, filesById, request, listener);
             case NEED_INGEST -> onNeedIngest(response, filesById, request, listener);
-            case CONVERT_MARKDOWN -> onConvertMarkdown(response, filesById, listener);
             case TOOL_CALL -> onToolCall(response, filesById, listener);
             case PLAN -> onPlan(response, filesById, request, listener);
             case ANSWER -> onAnswer(response, filesById, request, listener);
@@ -333,72 +331,6 @@ private WorkflowState onNeedIngest(
         return new WorkflowState.Pending(nextRequest);
     }
 
-    /**
-     * Deterministically convert each requested PDF to Markdown via the {@code
-     * /convert/pdf/markdown} endpoint (backed by {@code PdfMarkdownConverter}) and return the
-     * {@code .md} file(s) as a completed result. No AI resume — the conversion output is the final
-     * answer.
-     */
-    private WorkflowState onConvertMarkdown(
-            AiWorkflowResponse response,
-            Map<String, MultipartFile> filesById,
-            ProgressListener listener) {
-        List<AiFile> filesToConvert = response.getFilesToIngest();
-        if (filesToConvert == null || filesToConvert.isEmpty()) {
-            return new WorkflowState.Terminal(
-                    cannotContinue(
-                            "AI engine requested markdown conversion without listing any files."));
-        }
-
-        try {
-            List<Resource> resultFiles = new ArrayList<>();
-            List<String> inputNames = new ArrayList<>();
-            for (int i = 0; i < filesToConvert.size(); i++) {
-                AiFile file = filesToConvert.get(i);
-                MultipartFile multipartFile = filesById.get(file.getId());
-                if (multipartFile == null) {
-                    return new WorkflowState.Terminal(
-                            cannotContinue(
-                                    "AI engine requested markdown conversion for unknown file: "
-                                            + file.getName()));
-                }
-                listener.onProgress(
-                        AiWorkflowProgressEvent.executingTool(
-                                PDF_TO_MARKDOWN_ENDPOINT, i + 1, filesToConvert.size()));
-                Resource input = toResource(multipartFile);
-                PipelineDefinition definition =
-                        new PipelineDefinition(
-                                "convert-markdown",
-                                List.of(new PipelineStep(PDF_TO_MARKDOWN_ENDPOINT, Map.of())),
-                                null);
-                PolicyExecutionResult result =
-                        policyExecutor.execute(
-                                definition,
-                                PolicyInputs.of(List.of(input)),
-                                PolicyProgressListener.NOOP);
-                resultFiles.addAll(result.files());
-                inputNames.add(multipartFile.getOriginalFilename());
-            }
-            return new WorkflowState.Terminal(
-                    buildCompletedResponse(null, resultFiles, inputNames, null));
-        } catch (InternalApiTimeoutException e) {
-            log.error("PDF to Markdown conversion timed out: {}", e.getMessage());
-            return new WorkflowState.Terminal(
-                    cannotContinue(toolTimeoutMessage(PDF_TO_MARKDOWN_ENDPOINT, e)));
-        } catch (Exception e) {
-            AiWorkflowResponse limit = paygLimitResponseOrNull(e);
-            if (limit != null) {
-                log.info(
-                        "AI markdown conversion blocked by downstream entitlement gate ({})",
-                        limit.getErrorCode());
-                return new WorkflowState.Terminal(limit);
-            }
-            log.error("Failed to convert PDF to Markdown: {}", e.getMessage(), e);
-            return new WorkflowState.Terminal(
-                    cannotContinue(toolFailureMessage(PDF_TO_MARKDOWN_ENDPOINT, e)));
-        }
-    }
-
     private Resource toResource(MultipartFile file) throws IOException {
         TempFile tempFile = tempFileManager.createManagedTempFile("ai-workflow");
         file.transferTo(tempFile.getPath());

app/proprietary/src/test/java/stirling/software/proprietary/service/AiWorkflowServiceMoreTest.java

@@ -221,34 +221,6 @@ void unknownIngestFile() throws IOException {
         }
     }
 
-    @Nested
-    @DisplayName("convert_markdown guards")
-    class ConvertMarkdownGuards {
-
-        @Test
-        @DisplayName("no files listed yields CANNOT_CONTINUE")
-        void noFiles() throws IOException {
-            stubOrchestrator("{\"outcome\":\"convert_markdown\",\"filesToIngest\":[]}");
-            AiWorkflowResponse result = service.orchestrate(requestFor(pdf("a.pdf", "x"), "to md"));
-            assertThat(result.getOutcome()).isEqualTo(AiWorkflowOutcome.CANNOT_CONTINUE);
-        }
-
-        @Test
-        @DisplayName("unknown file id yields CANNOT_CONTINUE")
-        void unknownFile() throws IOException {
-            when(fileIdStrategy.idFor(any())).thenReturn("real-id");
-            stubOrchestrator(
-                    """
-                    {"outcome":"convert_markdown",
-                     "filesToIngest":[{"id":"other-id","name":"other.pdf"}]}
-                    """);
-            AiWorkflowResponse result =
-                    service.orchestrate(requestFor(pdf("real.pdf", "x"), "to md"));
-            assertThat(result.getOutcome()).isEqualTo(AiWorkflowOutcome.CANNOT_CONTINUE);
-            assertThat(result.getReason()).contains("other.pdf");
-        }
-    }
-
     @Nested
     @DisplayName("plan guards and errors")
     class PlanGuardsAndErrors {

app/proprietary/src/test/java/stirling/software/proprietary/service/AiWorkflowServiceTest.java

@@ -78,6 +78,7 @@ class AiWorkflowServiceTest {
     private static final String SPLIT_ENDPOINT = "/api/v1/general/split-pages";
     private static final String MERGE_ENDPOINT = "/api/v1/general/merge-pdfs";
     private static final String COMPRESS_ENDPOINT = "/api/v1/misc/compress-pdf";
+    private static final String MARKDOWN_ENDPOINT = "/api/v1/convert/pdf/markdown";
 
     @Mock private CustomPDFDocumentFactory pdfDocumentFactory;
     @Mock private AiEngineClient aiEngineClient;
@@ -440,32 +441,31 @@ void generateFileStoresContentDirectlyWithoutToolCall() throws IOException {
     }
 
     @Test
-    void convertMarkdownRunsDeterministicConversionAndReturnsMdFile() throws IOException {
+    void planWithMarkdownStepReturnsMdFile() throws IOException {
+        // PDF→Markdown is a normal tool the edit agent emits as a plan step (no bespoke
+        // outcome); the plan executor runs the converter and returns the .md file.
         MockMultipartFile input = pdf("multi-column-test_lorem.pdf", "pdf-bytes");
-        when(fileIdStrategy.idFor(any())).thenReturn("doc-1");
         stubOrchestrator(
                 """
                 {
-                  "outcome":"convert_markdown",
-                  "reason":"PDF to Markdown requested.",
-                  "filesToIngest":[{"id":"doc-1","name":"multi-column-test_lorem.pdf"}]
+                  "outcome":"plan",
+                  "summary":"Convert to Markdown",
+                  "steps":[{"tool":"%s","parameters":{}}]
                 }
-                """);
-        when(toolMetadataService.shouldUnpackZipResponse("/api/v1/convert/pdf/markdown"))
-                .thenReturn(false);
-        stubEndpoint(
-                "/api/v1/convert/pdf/markdown",
-                pdfResource("# Title", "multi-column-test_lorem.md"));
-        AtomicInteger ids = stubFileStorage();
+                """
+                        .formatted(MARKDOWN_ENDPOINT));
+        when(toolMetadataService.isMultiInput(anyString())).thenReturn(false);
+        when(toolMetadataService.shouldUnpackZipResponse(anyString())).thenReturn(false);
+        stubEndpoint(MARKDOWN_ENDPOINT, pdfResource("# Title", "multi-column-test_lorem.md"));
+        stubFileStorage();
 
         AiWorkflowResponse result = service.orchestrate(requestFor(input, "convert to markdown"));
 
         assertEquals(AiWorkflowOutcome.COMPLETED, result.getOutcome());
         assertEquals(1, result.getResultFiles().size());
         // Extension changes (pdf -> md), so the converter's response filename wins.
         assertEquals("multi-column-test_lorem.md", result.getResultFiles().get(0).getFileName());
-        assertEquals(1, ids.get());
-        verify(internalApiClient, times(1)).post(eq("/api/v1/convert/pdf/markdown"), any());
+        verify(internalApiClient, times(1)).post(eq(MARKDOWN_ENDPOINT), any());
     }
 
     @Test

engine/scripts/generate_tool_models.py

@@ -59,6 +59,36 @@ class ToolDiscovery:
         "/api/v1/convert/",
     )
 
+    # Endpoints under the allowed prefixes that are NOT edit-agent operations. A listed
+    # path and everything nested under it is dropped. Several kinds live here:
+    EXCLUDED_PATHS = (
+        # 1. Cert-signing family: needs certificate/key files the agent can't supply, plus
+        #    interactive session and hardware-token management. The whole subtree is dropped.
+        "/api/v1/security/cert-sign",
+        # 2. Interactive PDF text-editor endpoints, not one-shot operations.
+        "/api/v1/convert/pdf/text-editor",
+        "/api/v1/convert/text-editor/pdf",
+        # 3. Introspection / query endpoints that return metadata, a listing, or a
+        #    verification verdict rather than a transformed document, so they belong to
+        #    the question path, not the edit agent. (decompress is a dev-only stream op.)
+        "/api/v1/security/get-info-on-pdf",
+        "/api/v1/security/verify-pdf",
+        "/api/v1/security/validate-signature",
+        "/api/v1/misc/list-attachments",
+        "/api/v1/misc/show-javascript",
+        "/api/v1/misc/decompress-pdf",
+        "/api/v1/general/extract-bookmarks",
+        # 4. Require a secondary file (image, overlay PDF, attachments) on top of the input
+        #    PDF. The agent only ever supplies the input PDF(s), so these can never run.
+        #    (add-stamp / add-watermark stay: their text mode needs no extra file.)
+        "/api/v1/misc/add-image",
+        "/api/v1/misc/add-attachments",
+        "/api/v1/general/overlay-pdfs",
+    )
+
+    def _is_excluded(self, path: str) -> bool:
+        return any(path == p or path.startswith(p + "/") for p in self.EXCLUDED_PATHS)
+
     def __init__(self, spec: dict[str, Any]):
         resource = Resource.from_contents(spec, default_specification=DRAFT202012)
         self.resolver = Registry().with_resource("", resource).resolver()
@@ -73,17 +103,15 @@ def discover(self) -> DiscoveryResult:
         for path, path_item in sorted(self.spec.get("paths", {}).items()):
             if "{" in path or not any(path.startswith(p) for p in self.ALLOWED_PATH_PREFIXES):
                 continue
+            if self._is_excluded(path):
+                continue
             body_schema = self._get_request_body_schema(path_item) or {}
             query_props = self._get_query_parameters(path_item)
             body_props = body_schema.get("properties") or {}
             # Body properties win on name collision — body is the canonical param source
             # for the existing tools; query params are additive.
             properties = {**query_props, **body_props}
-            if not properties:
-                continue
             clean_props = self._filter_properties(properties)
-            if not clean_props:
-                continue
 
             enum_name = _deduplicate(_path_to_enum_name(path), used_enum)
             class_name = _deduplicate(_path_to_class_name(path), used_class)

engine/src/stirling/agents/orchestrator.py

@@ -15,7 +15,6 @@
 from stirling.agents.user_spec import UserSpecAgent
 from stirling.contracts import (
     AgentDraftWorkflowResponse,
-    ConvertMarkdownResponse,
     ExtractedTextArtifact,
     OrchestratorRequest,
     OrchestratorResponse,
@@ -48,7 +47,7 @@ def __init__(self, runtime: AppRuntime) -> None:
                 ToolOutput(
                     self.delegate_pdf_edit,
                     name="delegate_pdf_edit",
-                    description="Delegate requests for PDF modifications and return the PDF edit result.",
+                    description="Delegate requests to modify or convert PDFs and return the PDF edit result.",
                 ),
                 ToolOutput(
                     self.delegate_pdf_question,
@@ -71,13 +70,6 @@ def __init__(self, runtime: AppRuntime) -> None:
                         " feedback')."
                     ),
                 ),
-                ToolOutput(
-                    self.delegate_pdf_ingest,
-                    name="delegate_pdf_ingest",
-                    description=(
-                        "Delegate requests to convert a PDF to Markdown or extract its content as readable text."
-                    ),
-                ),
                 ToolOutput(
                     self.delegate_pdf_create,
                     name="delegate_pdf_create",
@@ -98,16 +90,14 @@ def __init__(self, runtime: AppRuntime) -> None:
             system_prompt=(
                 "You are the top-level orchestrator. "
                 "Choose exactly one output function that best handles the request. "
-                "Use delegate_pdf_edit for any requested modification of one or more PDFs. "
+                "Use delegate_pdf_edit for any request to modify or convert one or more PDFs. "
                 "Use delegate_pdf_question for questions about the contents of the attached PDFs. "
                 "Use delegate_user_spec for requests to create or define an agent spec. "
                 "Use delegate_pdf_review when the user wants the PDF returned with review"
                 " comments attached — anything like 'review this', 'annotate with comments',"
                 " 'leave feedback on the PDF'. "
                 "Use delegate_pdf_create when the user wants to generate a new document from"
                 " scratch with no input file — invoices, reports, letters, contracts, etc. "
-                "Use delegate_pdf_ingest for any request to convert a PDF to Markdown "
-                "or extract its content as readable text. "
                 "Use unsupported_capability when the user asks about the assistant itself "
                 "or when none of the other outputs fit; supply a helpful message."
             ),
@@ -177,13 +167,6 @@ async def delegate_user_spec(self, ctx: RunContext[OrchestratorDeps]) -> AgentDr
     async def _run_agent_draft(self, request: OrchestratorRequest) -> AgentDraftWorkflowResponse:
         return await UserSpecAgent(self.runtime).orchestrate(request)
 
-    async def delegate_pdf_ingest(self, ctx: RunContext[OrchestratorDeps]) -> ConvertMarkdownResponse:
-        request = ctx.deps.request
-        return ConvertMarkdownResponse(
-            reason="PDF to Markdown requested — Java converts deterministically.",
-            files_to_ingest=request.files,
-        )
-
     async def delegate_pdf_review(self, ctx: RunContext[OrchestratorDeps]) -> PdfReviewOrchestrateResponse:
         return await self._run_pdf_review(ctx.deps.request)
 

engine/src/stirling/contracts/__init__.py

@@ -13,7 +13,6 @@
     AiFile,
     ArtifactKind,
     ConversationMessage,
-    ConvertMarkdownResponse,
     ExtractedFileText,
     GenerateFileResponse,
     MathAuditorToolReportArtifact,
@@ -163,7 +162,6 @@
     "NeedContentFileRequest",
     "NeedContentResponse",
     "NeedIngestResponse",
-    "ConvertMarkdownResponse",
     "NextExecutionAction",
     "OrchestratorRequest",
     "OrchestratorResponse",

engine/src/stirling/contracts/common.py

@@ -62,7 +62,6 @@ class WorkflowOutcome(StrEnum):
     CANNOT_CONTINUE = "cannot_continue"
     UNSUPPORTED_CAPABILITY = "unsupported_capability"
     GENERATE_FILE = "generate_file"
-    CONVERT_MARKDOWN = "convert_markdown"
 
 
 class ArtifactKind(StrEnum):
@@ -184,19 +183,6 @@ class NeedIngestResponse(ApiModel):
     content_types: list[PdfContentType] = Field(default_factory=list)
 
 
-class ConvertMarkdownResponse(ApiModel):
-    """Terminal signal: convert the listed files to Markdown deterministically.
-
-    This is a deterministic, non-AI conversion. Java runs the PDF→Markdown converter
-    (``PdfMarkdownConverter``) on each file and returns the resulting ``.md`` file(s) as a
-    completed result. There is no resume turn — the conversion output is the final answer.
-    """
-
-    outcome: Literal[WorkflowOutcome.CONVERT_MARKDOWN] = WorkflowOutcome.CONVERT_MARKDOWN
-    reason: str
-    files_to_ingest: list[AiFile]
-
-
 class ToolOperationStep(ApiModel):
     kind: Literal[StepKind.TOOL] = StepKind.TOOL
     tool: AnyToolId

engine/src/stirling/contracts/orchestrator.py

@@ -11,7 +11,6 @@
     AiFile,
     ArtifactKind,
     ConversationMessage,
-    ConvertMarkdownResponse,
     ExtractedFileText,
     GenerateFileResponse,
     NeedContentResponse,
@@ -61,7 +60,6 @@ class UnsupportedCapabilityResponse(ApiModel):
     | GenerateFileResponse
     | NeedContentResponse
     | NeedIngestResponse
-    | ConvertMarkdownResponse
     | AgentDraftResponse
     | NextExecutionAction
     | UnsupportedCapabilityResponse,