refactor: Simplify file handling in programmatic execution and enhance timeout management

- Updated `ProgrammaticExecutionRequest` to accept only `CodeEnvFile` references, removing legacy inline file support.
- Refined timeout conversion logic in `programmatic.py` for clarity.
- Removed unused state restoration fields from `FileInfo` model and related services to streamline state management.
- Adjusted `ProgrammaticService` to focus solely on mounting referenced files, enhancing code readability.
- Cleaned up various comments and documentation to reflect the current state of the codebase.

Author: usnavy13

docs/PROGRAMMATIC_TOOL_CALLING.md

@@ -59,7 +59,7 @@ interface ProgrammaticExecutionRequest {
   tools: LCTool[]; // Filtered tool definitions
   session_id?: string; // Optional: for file persistence
   timeout?: number; // 1000-300000ms (default: 60000)
-  files?: Array<CodeEnvFile | InlinePTCFile>; // Optional: initial sandbox files
+  files?: CodeEnvFile[]; // Optional: initial sandbox files
 }
 
 interface LCTool {
@@ -73,11 +73,6 @@ interface CodeEnvFile {
   name: string; // Original filename
   session_id: string; // Source session
 }
-
-interface InlinePTCFile {
-  filename: string;
-  content: string; // Legacy inline payload, still accepted
-}
 ```
 
 The public timeout contract is milliseconds. The backend converts that value to
@@ -249,7 +244,7 @@ Unlike `/exec`, sandboxes for programmatic execution must:
 - Have **longer TTL** (match request timeout, up to 5 minutes)
 - Be **cleaned up** on completion, error, or timeout
 - Support **session file access** at `/mnt/data/`
-- Accept LibreChat `CodeEnvFile` references without requiring inline file blobs
+- Accept only LibreChat `CodeEnvFile` references for prior-session files
 
 ### 4. Round-Trip Limits
 

src/api/programmatic.py

@@ -8,7 +8,7 @@
 from typing import Optional
 
 import structlog
-from fastapi import APIRouter, Request
+from fastapi import APIRouter
 
 from ..models.programmatic import (
     ProgrammaticExecRequest,
@@ -38,13 +38,12 @@ def _timeout_ms_to_seconds(timeout_ms: Optional[int]) -> Optional[int]:
     """Convert the public millisecond timeout contract to internal seconds."""
     if timeout_ms is None:
         return None
-    return max(1, math.ceil(timeout_ms / 1000))
+    return math.ceil(timeout_ms / 1000)
 
 
 @router.post("/exec/programmatic", response_model=ProgrammaticExecResponse)
 async def execute_programmatic(
     request: ProgrammaticExecRequest,
-    http_request: Request,
     session_service: SessionServiceDep,
 ) -> ProgrammaticExecResponse:
     """Execute code with programmatic tool calling support.
@@ -55,7 +54,6 @@ async def execute_programmatic(
 
     Args:
         request: PTC execution request
-        http_request: HTTP request for auth state
         session_service: Session service for session management
 
     Returns:

src/middleware/security.py

@@ -120,12 +120,9 @@ async def _validate_request(self, request: Request):
         """Validate request content type."""
         # Only validate content type for non-file upload requests.
         # File uploads are handled by the files API with specific validation.
-        # Keep /state/* exempt so legacy paths return router-level 404 rather
-        # than a middleware 415 when clients send binary content.
         if (
             request.method in ["POST", "PUT", "PATCH"]
             and not request.url.path.startswith("/upload")
-            and not request.url.path.startswith("/state/")
         ):
             content_type = request.headers.get("content-type", "")
             allowed_types = [

src/models/files.py

@@ -40,18 +40,6 @@ class FileInfo(BaseModel):
     content_type: str
     created_at: datetime
     path: str = Field(..., description="File path in the session")
-    # State restoration fields (for Python state-file linking)
-    execution_id: Optional[str] = Field(
-        default=None, description="ID of the execution that created/last used this file"
-    )
-    state_hash: Optional[str] = Field(
-        default=None,
-        description="SHA256 hash of the Python state when this file was last used",
-    )
-    last_used_at: Optional[datetime] = Field(
-        default=None,
-        description="Timestamp of when this file was last used in an execution",
-    )
 
     class Config:
         json_encoders = {datetime: lambda v: v.isoformat()}

src/models/programmatic.py

@@ -48,25 +48,13 @@ class PTCToolResult(BaseModel):
 class PTCFileInput(BaseModel):
     """File payload for PTC initial execution.
 
-    Supports both:
-    - LibreChat-style file references: {session_id, id, name}
-    - Legacy inline files: {filename, content}
+    Matches the LibreChat/librechat-agents CodeEnvFile shape:
+    {session_id, id, name}
     """
 
-    id: Optional[str] = Field(default=None, description="File identifier")
-    name: Optional[str] = Field(
-        default=None, description="Filename for a referenced session file"
-    )
-    session_id: Optional[str] = Field(
-        default=None, description="Source session for a referenced file"
-    )
-    filename: Optional[str] = Field(
-        default=None, description="Filename for inline file content"
-    )
-    content: Optional[Any] = Field(
-        default=None,
-        description="Inline file content for non-reference callers",
-    )
+    id: str = Field(..., description="File identifier")
+    name: str = Field(..., description="Original filename for the referenced file")
+    session_id: str = Field(..., description="Source session for a referenced file")
 
 
 class ProgrammaticExecRequest(BaseModel):
@@ -102,7 +90,8 @@ class ProgrammaticExecRequest(BaseModel):
         le=300000,
     )
     files: List[PTCFileInput] = Field(
-        default_factory=list, description="Files to mount in sandbox"
+        default_factory=list,
+        description="Referenced prior-session files to mount in the sandbox",
     )
 
     # Continuation fields

src/services/file.py

@@ -287,24 +287,13 @@ async def get_file_info(self, session_id: str, file_id: str) -> Optional[FileInf
         if not metadata:
             return None
 
-        # Parse last_used_at if present
-        last_used_at = None
-        if metadata.get("last_used_at"):
-            try:
-                last_used_at = datetime.fromisoformat(metadata["last_used_at"])
-            except (ValueError, TypeError):
-                pass
-
         return FileInfo(
             file_id=file_id,
             filename=metadata["filename"],
             size=metadata["size"],
             content_type=metadata["content_type"],
             created_at=metadata["created_at"],
             path=metadata["path"],
-            execution_id=metadata.get("execution_id"),
-            state_hash=metadata.get("state_hash"),
-            last_used_at=last_used_at,
         )
 
     async def list_files(self, session_id: str) -> List[FileInfo]:
@@ -454,17 +443,13 @@ async def store_execution_output_file(
         session_id: str,
         filename: str,
         content: bytes,
-        execution_id: Optional[str] = None,
-        state_hash: Optional[str] = None,
     ) -> str:
         """Store a file generated during code execution.
 
         Args:
             session_id: Session identifier
             filename: Name of the file
             content: File content as bytes
-            execution_id: Optional ID of the execution that created this file
-            state_hash: Optional SHA256 hash of the Python state at creation time
 
         Returns:
             The generated file_id
@@ -496,7 +481,6 @@ async def store_execution_output_file(
 
             now = datetime.utcnow()
 
-            # Store metadata including state restoration fields
             metadata = {
                 "file_id": file_id,
                 "filename": filename,
@@ -509,13 +493,6 @@ async def store_execution_output_file(
                 "type": "output",  # Mark as execution output
             }
 
-            # Add state restoration fields if provided
-            if execution_id:
-                metadata["execution_id"] = execution_id
-            if state_hash:
-                metadata["state_hash"] = state_hash
-                metadata["last_used_at"] = now.isoformat()
-
             await self._store_file_metadata(session_id, file_id, metadata)
 
             logger.debug(
@@ -822,84 +799,11 @@ async def cleanup_orphan_objects(self, batch_limit: int = 1000) -> int:
             logger.error("Orphan MinIO objects cleanup failed", error=str(e))
             return 0
 
-    async def get_file_state_hash(self, session_id: str, file_id: str) -> Optional[str]:
-        """Get the state hash associated with a file.
-
-        Args:
-            session_id: Session identifier
-            file_id: File identifier
-
-        Returns:
-            SHA256 hash of the state when this file was last used, or None
-        """
-        try:
-            metadata_key = self.get_file_metadata_key(session_id, file_id)
-            state_hash = await self.redis_client.hget(metadata_key, "state_hash")
-            return state_hash
-        except Exception as e:
-            logger.error(
-                "Failed to get file state hash",
-                error=str(e),
-                session_id=session_id,
-                file_id=file_id,
-            )
-            return None
-
-    async def update_file_state_hash(
-        self,
-        session_id: str,
-        file_id: str,
-        state_hash: str,
-        execution_id: Optional[str] = None,
-    ) -> bool:
-        """Update the state hash for a file (called when file is used in execution).
-
-        Args:
-            session_id: Session identifier
-            file_id: File identifier
-            state_hash: New SHA256 hash of the Python state
-            execution_id: Optional ID of the execution that used this file
-
-        Returns:
-            True if update was successful
-        """
-        try:
-            metadata_key = self.get_file_metadata_key(session_id, file_id)
-            now = datetime.utcnow().isoformat()
-
-            # Update multiple fields atomically
-            updates = {
-                "state_hash": state_hash,
-                "last_used_at": now,
-            }
-            if execution_id:
-                updates["execution_id"] = execution_id
-
-            await self.redis_client.hset(metadata_key, mapping=updates)
-
-            logger.debug(
-                "Updated file state hash",
-                session_id=session_id[:12],
-                file_id=file_id,
-                state_hash=state_hash[:12],
-            )
-            return True
-        except Exception as e:
-            logger.error(
-                "Failed to update file state hash",
-                error=str(e),
-                session_id=session_id,
-                file_id=file_id,
-            )
-            return False
-
     async def update_file_content(
         self,
         session_id: str,
         file_id: str,
         content: bytes,
-        state_hash: Optional[str] = None,
-        execution_id: Optional[str] = None,
     ) -> bool:
         """Update the content of an existing file.
 
@@ -910,8 +814,6 @@ async def update_file_content(
             session_id: Session identifier
             file_id: File identifier
             content: New file content as bytes
-            state_hash: Optional SHA256 hash of the Python state
-            execution_id: Optional ID of the execution that modified this file
 
         Returns:
             True if update was successful
@@ -955,15 +857,9 @@ async def update_file_content(
             )
 
             # Update metadata
-            now = datetime.utcnow().isoformat()
             updates = {
                 "size": len(content),
-                "last_used_at": now,
             }
-            if state_hash:
-                updates["state_hash"] = state_hash
-            if execution_id:
-                updates["execution_id"] = execution_id
 
             metadata_key = self.get_file_metadata_key(session_id, file_id)
             await self.redis_client.hset(metadata_key, mapping=updates)