feat: Enhance file upload and listing with resource kind and version support

Updated the upload_files_batch and list_files functions to include support for resource kind and version parameters. The upload logic now marks files as agent files based on the kind provided. Additionally, the RequestFile and FileRef models have been updated to accept resource_id, kind, and version fields, with corresponding tests added to validate these changes.

Author: usnavy13

src/api/files.py

@@ -250,7 +250,10 @@ async def upload_files_batch(
     entity_id: Optional[str] = (
         entity_id_raw if isinstance(entity_id_raw, str) and entity_id_raw else None
     )
-    is_agent_file = entity_id is not None
+    kind_raw = form.get("kind")
+    is_agent_file = entity_id is not None or (
+        isinstance(kind_raw, str) and kind_raw in ("skill", "agent")
+    )
 
     read_only_raw = form.get("read_only")
     is_read_only = isinstance(read_only_raw, str) and read_only_raw.lower() in (
@@ -355,6 +358,18 @@ async def list_files(
         None,
         description="Detail level: 'simple' for basic info, otherwise full details",
     ),
+    kind: Optional[str] = Query(
+        None,
+        description="Resource kind filter: 'skill', 'agent', or 'user'",
+    ),
+    id: Optional[str] = Query(
+        None,
+        description="Resource id for scoped file listing",
+    ),
+    version: Optional[int] = Query(
+        None,
+        description="Resource version (only meaningful when kind=skill)",
+    ),
     file_service: FileServiceDep = None,
 ):
     """List all files in a session with optional detail parameter - LibreChat compatible."""

src/models/exec.py

@@ -19,6 +19,9 @@ class FileRef(BaseModel):
     session_id: Optional[str] = None
     inherited: Optional[bool] = None
     entity_id: Optional[str] = None
+    resource_id: Optional[str] = None
+    kind: Optional[str] = None
+    version: Optional[int] = None
     modified_from: Optional[Dict[str, str]] = None
 
     @computed_field  # type: ignore[prop-decorator]
@@ -38,6 +41,9 @@ class RequestFile(BaseModel):
     )
     name: str
     entity_id: Optional[str] = None
+    resource_id: Optional[str] = None
+    kind: Optional[str] = None
+    version: Optional[int] = None
 
 
 class ExecRequest(BaseModel):

src/models/programmatic.py

@@ -63,6 +63,9 @@ class PTCFileInput(BaseModel):
         description="Source session for a referenced file",
         validation_alias=AliasChoices("storage_session_id", "session_id"),
     )
+    resource_id: Optional[str] = None
+    kind: Optional[str] = None
+    version: Optional[int] = None
 
 
 class ProgrammaticExecRequest(BaseModel):

tests/integration/test_librechat_compat.py

@@ -2041,6 +2041,50 @@ def test_nested_filename_preserved_in_response(
         # The stored filename also preserves the path so S3/sandbox round-trip works.
         assert "skills/weather_lookup/SKILL.md" in setup_mocks["stored"]
 
+    def test_kind_skill_marks_files_as_agent(self, client, auth_headers, setup_mocks):
+        """kind=skill bypasses extension whitelist for skill-priming uploads."""
+        files = [
+            ("file", ("schema.xsd", io.BytesIO(b"<xs:schema/>"), "application/xml"))
+        ]
+        data = {"kind": "skill", "id": "skill_abc123", "version": "3"}
+        response = client.post(
+            "/upload/batch", files=files, data=data, headers=auth_headers
+        )
+
+        assert response.status_code == 200
+        store = setup_mocks["file_service"].store_uploaded_file
+        assert store.await_count == 1
+        kwargs = store.await_args.kwargs
+        assert kwargs["is_agent_file"] is True
+
+    def test_kind_agent_marks_files_as_agent(self, client, auth_headers, setup_mocks):
+        """kind=agent also bypasses extension whitelist."""
+        files = [
+            ("file", ("config.toml", io.BytesIO(b"[tool]"), "application/toml"))
+        ]
+        data = {"kind": "agent", "id": "agent_xyz"}
+        response = client.post(
+            "/upload/batch", files=files, data=data, headers=auth_headers
+        )
+
+        assert response.status_code == 200
+        store = setup_mocks["file_service"].store_uploaded_file
+        assert store.await_count == 1
+        kwargs = store.await_args.kwargs
+        assert kwargs["is_agent_file"] is True
+
+    def test_batch_response_includes_storage_session_id(
+        self, client, auth_headers, setup_mocks
+    ):
+        """LibreChat validates storage_session_id in batch upload response."""
+        files = [("file", ("data.csv", io.BytesIO(b"a,b"), "text/csv"))]
+        response = client.post("/upload/batch", files=files, headers=auth_headers)
+
+        assert response.status_code == 200
+        body = response.json()
+        assert "storage_session_id" in body
+        assert body["storage_session_id"] == body["session_id"]
+
 
 # =============================================================================
 # GET /sessions/{session_id}/objects/{file_id} — liveness probe

tests/unit/test_exec_models.py

@@ -91,6 +91,52 @@ def test_fileref_emits_both_session_id_and_storage_session_id(self):
         assert dumped["session_id"] == "sess-1"
 
 
+class TestCodeEnvFileFields:
+    """RequestFile and FileRef accept resource_id, kind, and version
+    fields sent by the librechat-agents CodeEnvFile type."""
+
+    def test_request_file_accepts_code_env_file_shape(self):
+        rf = RequestFile(
+            id="fid",
+            storage_session_id="sess",
+            name="data.csv",
+            resource_id="res-1",
+            kind="skill",
+            version=3,
+        )
+        assert rf.session_id == "sess"
+        assert rf.resource_id == "res-1"
+        assert rf.kind == "skill"
+        assert rf.version == 3
+
+    def test_request_file_code_env_fields_optional(self):
+        rf = RequestFile(id="fid", session_id="sess", name="data.csv")
+        assert rf.resource_id is None
+        assert rf.kind is None
+        assert rf.version is None
+
+    def test_fileref_resource_id_kind_version(self):
+        ref = FileRef(
+            id="fid",
+            name="out.png",
+            session_id="sess-1",
+            resource_id="res-1",
+            kind="skill",
+            version=2,
+        )
+        dumped = ref.model_dump(exclude_none=True)
+        assert dumped["resource_id"] == "res-1"
+        assert dumped["kind"] == "skill"
+        assert dumped["version"] == 2
+
+    def test_fileref_code_env_fields_excluded_when_none(self):
+        ref = FileRef(id="fid", name="out.png", session_id="sess-1")
+        dumped = ref.model_dump(exclude_none=True)
+        assert "resource_id" not in dumped
+        assert "kind" not in dumped
+        assert "version" not in dumped
+
+
 class TestExecRequestTimeout:
     """ExecRequest.timeout: optional, milliseconds, range 1000-300000."""