Feature/pdf to markdown agent (#6271)

Co-authored-by: James Brunton <[email protected]>

engine/src/stirling/contracts/common.py

@@ -61,6 +61,7 @@ class WorkflowOutcome(StrEnum):
     COMPLETED = "completed"
     CANNOT_CONTINUE = "cannot_continue"
     UNSUPPORTED_CAPABILITY = "unsupported_capability"
+    GENERATE_FILE = "generate_file"
 
 
 class ArtifactKind(StrEnum):
@@ -70,6 +71,7 @@ class ArtifactKind(StrEnum):
     """
 
     EXTRACTED_TEXT = "extracted_text"
+    PAGE_LAYOUT = "page_layout"
     TOOL_REPORT = "tool_report"
 
 
@@ -89,6 +91,7 @@ class SupportedCapability(StrEnum):
     AGENT_REVISE = "agent_revise"
     AGENT_NEXT_ACTION = "agent_next_action"
     MATH_AUDITOR_AGENT = "math_auditor_agent"
+    PDF_TO_MARKDOWN = "pdf_to_markdown"
 
 
 class ConversationMessage(ApiModel):
@@ -200,6 +203,19 @@ class ToolOperationStep(ApiModel):
         return self
 
 
+class GenerateFileResponse(ApiModel):
+    """Return generated text content directly to Java for file packaging.
+
+    Java converts the content string to bytes and stores it as a result file,
+    avoiding a round-trip through a write-file tool endpoint.
+    """
+
+    outcome: Literal[WorkflowOutcome.GENERATE_FILE] = WorkflowOutcome.GENERATE_FILE
+    content: str
+    filename: str = Field(pattern=r"^[^/\\]+$", description="Output filename; no path separators.")
+    summary: str | None = None
+
+
 def drop_unknown_tool_endpoints(value: Iterable[str | ToolEndpoint]) -> list[ToolEndpoint]:
     """Coerce inbound endpoint identifiers into `ToolEndpoint` members, dropping unknowns.