refactor: Rename session_id to storage_session_id across API and models

Updated the API responses and models to replace all instances of session_id with storage_session_id for consistency. This change includes updates to the upload, list, and batch file operations, as well as adjustments in the corresponding tests and documentation to reflect the new naming convention.

Author: usnavy13

src/api/files.py

@@ -172,6 +172,7 @@ async def upload_file(
         # Note: Production API returns different format with fileId instead of id
         return {
             "message": "success",
+            "storage_session_id": session_id,
             "session_id": session_id,
             "files": [
                 {"filename": file["name"], "fileId": file["id"]}
@@ -339,6 +340,7 @@ async def upload_files_batch(
 
     return {
         "message": message,
+        "storage_session_id": session_id,
         "session_id": session_id,
         "files": results,
         "succeeded": succeeded,
@@ -408,6 +410,7 @@ async def list_files(
                     {
                         "name": f"{session_id}/{file_info.file_id}",
                         "id": file_info.file_id,
+                        "storage_session_id": session_id,
                         "session_id": session_id,
                         "content": None,  # Not returned in list
                         "size": file_info.size,

src/models/exec.py

@@ -5,26 +5,37 @@
 from typing import Dict, List, Optional, Any
 
 # Third-party imports
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, computed_field
 
 
 class FileRef(BaseModel):
     """File reference model for execution response."""
 
+    model_config = ConfigDict(populate_by_name=True)
+
     id: str
     name: str
-    path: Optional[str] = None  # Make path optional
-    session_id: Optional[str] = None  # Session ID for cross-message file persistence
+    path: Optional[str] = None
+    session_id: Optional[str] = None
     inherited: Optional[bool] = None
     entity_id: Optional[str] = None
     modified_from: Optional[Dict[str, str]] = None
 
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def storage_session_id(self) -> Optional[str]:
+        return self.session_id
+
 
 class RequestFile(BaseModel):
     """Request file model."""
 
+    model_config = ConfigDict(populate_by_name=True)
+
     id: str
-    session_id: str
+    session_id: str = Field(
+        validation_alias=AliasChoices("storage_session_id", "session_id"),
+    )
     name: str
     entity_id: Optional[str] = None
 

src/models/programmatic.py

@@ -8,7 +8,7 @@
 
 from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel, Field, validator
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, validator
 
 SUPPORTED_PTC_LANGUAGES = {"py", "bash"}
 
@@ -51,12 +51,18 @@ class PTCFileInput(BaseModel):
     """File payload for PTC initial execution.
 
     Matches the LibreChat/librechat-agents CodeEnvFile shape:
-    {session_id, id, name}
+    {storage_session_id, id, name}
     """
 
+    model_config = ConfigDict(populate_by_name=True)
+
     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")
+    session_id: str = Field(
+        ...,
+        description="Source session for a referenced file",
+        validation_alias=AliasChoices("storage_session_id", "session_id"),
+    )
 
 
 class ProgrammaticExecRequest(BaseModel):

src/services/orchestrator.py

@@ -786,7 +786,8 @@ async def _handle_generated_files(self, ctx: ExecutionContext) -> List[FileRef]:
                 if meta.get("modified_from_id"):
                     file_ref.modified_from = {
                         "id": meta["modified_from_id"],
-                        "session_id": meta.get("modified_from_session_id") or "",
+                        "storage_session_id": meta.get("modified_from_session_id")
+                        or "",
                     }
                 generated.append(file_ref)
                 logger.debug(

tests/functional/test_client_replay.py

@@ -12,7 +12,7 @@ def _normalize_artifact_files(result: dict) -> list[dict]:
     session_id = result["session_id"]
     return [
         {
-            "session_id": file_info.get("session_id") or session_id,
+            "storage_session_id": file_info.get("storage_session_id") or session_id,
             "id": file_info["id"],
             "name": file_info["name"],
         }
@@ -36,7 +36,7 @@ async def _fetch_runtime_file_refs(
         file_id = name_parts[1].split(".")[0] if len(name_parts) > 1 else ""
         file_references.append(
             {
-                "session_id": session_id,
+                "storage_session_id": session_id,
                 "id": file_id,
                 "name": file_info["metadata"]["original-filename"],
             }
@@ -128,7 +128,7 @@ async def test_uploaded_files_follow_runtime_session_when_first_exec_has_no_outp
             data={"entity_id": unique_entity_id},
         )
         assert upload.status_code == 200, upload.text
-        upload_session_id = upload.json()["session_id"]
+        upload_session_id = upload.json()["storage_session_id"]
         upload_refs = await _fetch_runtime_file_refs(
             async_client, auth_headers, upload_session_id
         )
@@ -164,7 +164,7 @@ async def test_uploaded_files_survive_runtime_fallback_after_outputs_are_generat
             data={"entity_id": unique_entity_id},
         )
         assert upload.status_code == 200, upload.text
-        upload_session_id = upload.json()["session_id"]
+        upload_session_id = upload.json()["storage_session_id"]
         upload_refs = await _fetch_runtime_file_refs(
             async_client, auth_headers, upload_session_id
         )
@@ -298,7 +298,7 @@ async def test_ptc_fallback_refs_preserve_files_after_continuation(
         )
         assert upload.status_code == 200, upload.text
         upload_result = upload.json()
-        session_id = upload_result["session_id"]
+        session_id = upload_result["storage_session_id"]
 
         initial = await _start_ptc_like_runtime(
             async_client,

tests/functional/test_concurrent_file_exec.py

@@ -56,7 +56,7 @@ async def test_large_file_exec_does_not_block_concurrent_requests(
         assert upload_resp.status_code == 200, f"Upload failed: {upload_resp.text}"
 
         result = upload_resp.json()
-        session_id = result["session_id"]
+        session_id = result["storage_session_id"]
         file_id = result["files"][0]["fileId"]
         filename = result["files"][0]["filename"]
 
@@ -72,7 +72,7 @@ async def exec_with_file(idx: int) -> tuple:
                     "lang": "py",
                     "session_id": session_id,
                     "files": [
-                        {"id": file_id, "session_id": session_id, "name": filename}
+                        {"id": file_id, "storage_session_id": session_id, "name": filename}
                     ],
                 },
                 timeout=60.0,

tests/functional/test_exec_workflow.py

@@ -172,7 +172,7 @@ async def test_file_ref_does_not_leak_session_across_users(
         )
         assert upload.status_code == 200
         upload_data = upload.json()
-        upload_session = upload_data["session_id"]
+        upload_session = upload_data["storage_session_id"]
         file_id = upload_data["files"][0]["fileId"]
         filename = upload_data["files"][0]["filename"]
 
@@ -187,7 +187,7 @@ async def test_file_ref_does_not_leak_session_across_users(
                 "files": [
                     {
                         "id": file_id,
-                        "session_id": upload_session,
+                        "storage_session_id": upload_session,
                         "name": filename,
                     }
                 ],
@@ -208,7 +208,7 @@ async def test_file_ref_does_not_leak_session_across_users(
                 "files": [
                     {
                         "id": file_id,
-                        "session_id": upload_session,
+                        "storage_session_id": upload_session,
                         "name": filename,
                     }
                 ],

tests/functional/test_files.py

@@ -25,7 +25,7 @@ async def test_upload_single_file(
         result = response.json()
 
         assert result["message"] == "success"
-        assert "session_id" in result
+        assert "storage_session_id" in result
         assert len(result["files"]) == 1
         assert "fileId" in result["files"][0]
         assert "filename" in result["files"][0]
@@ -50,10 +50,10 @@ async def test_librechat_upload_format(
         assert response.json()["message"] == "success"
 
     @pytest.mark.asyncio
-    async def test_upload_returns_session_id(
+    async def test_upload_returns_storage_session_id(
         self, async_client, auth_headers, unique_entity_id
     ):
-        """Upload response includes session_id."""
+        """Upload response includes storage_session_id."""
         files = {"files": ("test.txt", b"content", "text/plain")}
         data = {"entity_id": unique_entity_id}
 
@@ -65,8 +65,8 @@ async def test_upload_returns_session_id(
         )
 
         result = response.json()
-        assert "session_id" in result
-        assert len(result["session_id"]) > 0
+        assert "storage_session_id" in result
+        assert len(result["storage_session_id"]) > 0
 
     @pytest.mark.asyncio
     async def test_upload_returns_file_info(
@@ -120,7 +120,7 @@ async def test_list_files_after_upload(
             files=files,
             data={"entity_id": unique_entity_id},
         )
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
 
         # List files
         response = await async_client.get(
@@ -145,7 +145,7 @@ async def test_list_files_detail_simple(
             files=files,
             data={"entity_id": unique_entity_id},
         )
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
 
         # List with simple detail
         response = await async_client.get(
@@ -170,7 +170,7 @@ async def test_list_files_detail_summary(
             files=files,
             data={"entity_id": unique_entity_id},
         )
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
 
         # List with summary detail
         response = await async_client.get(
@@ -204,7 +204,7 @@ async def test_detail_full_has_original_filename_metadata(
             data={"entity_id": unique_entity_id},
         )
         assert upload.status_code == 200
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
 
         # Get full detail
         response = await async_client.get(
@@ -237,7 +237,7 @@ async def test_detail_full_has_required_fields(
             files=files,
             data={"entity_id": unique_entity_id},
         )
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
 
         response = await async_client.get(
             f"/files/{session_id}?detail=full",
@@ -278,7 +278,7 @@ async def test_download_uploaded_file(
             data={"entity_id": unique_entity_id},
         )
 
-        session_id = upload.json()["session_id"]
+        session_id = upload.json()["storage_session_id"]
         file_id = upload.json()["files"][0]["fileId"]
 
         response = await async_client.get(
@@ -322,7 +322,7 @@ async def test_uploaded_file_readable_at_mnt_data(
         )
         assert upload.status_code == 200
         upload_data = upload.json()
-        session_id = upload_data["session_id"]
+        session_id = upload_data["storage_session_id"]
         file_id = upload_data["files"][0]["fileId"]
         filename = upload_data["files"][0]["filename"]
 
@@ -341,7 +341,7 @@ async def test_uploaded_file_readable_at_mnt_data(
                 ),
                 "lang": "py",
                 "session_id": session_id,
-                "files": [{"id": file_id, "session_id": session_id, "name": filename}],
+                "files": [{"id": file_id, "storage_session_id": session_id, "name": filename}],
             },
         )
 
@@ -366,7 +366,7 @@ async def test_uploaded_file_readable_via_relative_path(
             data={"entity_id": unique_entity_id},
         )
         upload_data = upload.json()
-        session_id = upload_data["session_id"]
+        session_id = upload_data["storage_session_id"]
         file_id = upload_data["files"][0]["fileId"]
         filename = upload_data["files"][0]["filename"]
 
@@ -377,7 +377,7 @@ async def test_uploaded_file_readable_via_relative_path(
                 "code": f"print(open('{filename}').read())",
                 "lang": "py",
                 "session_id": session_id,
-                "files": [{"id": file_id, "session_id": session_id, "name": filename}],
+                "files": [{"id": file_id, "storage_session_id": session_id, "name": filename}],
             },
         )
 
@@ -400,7 +400,7 @@ async def test_upload_execute_generate_download(
             data={"entity_id": unique_entity_id},
         )
         upload_data = upload.json()
-        session_id = upload_data["session_id"]
+        session_id = upload_data["storage_session_id"]
         file_id = upload_data["files"][0]["fileId"]
         filename = upload_data["files"][0]["filename"]
 
@@ -424,7 +424,7 @@ async def test_upload_execute_generate_download(
                 ),
                 "lang": "py",
                 "session_id": session_id,
-                "files": [{"id": file_id, "session_id": session_id, "name": filename}],
+                "files": [{"id": file_id, "storage_session_id": session_id, "name": filename}],
             },
         )
 

tests/functional/test_generated_artifacts.py

@@ -114,7 +114,7 @@ async def test_generated_file_is_reused_on_follow_up_execution(
                 "files": [
                     {
                         "id": generated_file["id"],
-                        "session_id": generate_result["session_id"],
+                        "storage_session_id": generate_result["session_id"],
                         "name": generated_file["name"],
                     }
                 ],