[NOT-860] feat(sdk): scope file storage to sessions

docs/src/llms.txt

@@ -422,8 +422,8 @@ The SDK docs below are for generated-code editing and reference. They are not th
 ### File Storage
 
 - [FileStorage](https://docs.notte.cc/sdk-reference/manual/file_storage.md): Upload and download files for your automations
-- [download](https://docs.notte.cc/sdk-reference/remotefilestorage/download.md): Stores a file that has been downloaded from a website in the current session
-- [upload](https://docs.notte.cc/sdk-reference/remotefilestorage/upload.md): Upload a file from your local machine to storage
+- [download](https://docs.notte.cc/sdk-reference/remotefilestorage/download.md): No description available
+- [upload](https://docs.notte.cc/sdk-reference/remotefilestorage/upload.md): No description available
 - [list_downloaded_files](https://docs.notte.cc/sdk-reference/remotefilestorage/list_downloaded_files.md): List all files in the download_dir
 - [list_uploaded_files](https://docs.notte.cc/sdk-reference/remotefilestorage/list_uploaded_files.md): List all files from the upload_dir
 

docs/src/sdk-reference/manual/session.mdx

@@ -111,10 +111,6 @@ You can use the default parameters to create your session, or customize them:
   The CDP URL of another remote session provider.
 </ParamField>
 
-<ParamField path="use_file_storage" type="bool">
-  Whether FileStorage should be attached to the session.
-</ParamField>
-
 <ParamField path="screenshot_type" type="typing.Literal['raw', 'full', 'last_action']">
   The type of screenshot to use for the session.
 </ParamField>

docs/src/sdk-reference/misc/filesource.mdx

@@ -0,0 +1,18 @@
+---
+title: "FileSource"
+description: "Enum where members are also (and must be) strings"
+---
+
+
+
+## Methods
+
+
+## Inheritance
+
+Inherits from: StrEnum
+
+
+## Module
+
+`notte_sdk.types`

docs/src/sdk-reference/misc/listfilesresponse.mdx

@@ -0,0 +1,26 @@
+---
+title: "ListFilesResponse"
+description: ""
+---
+
+
+
+## Fields
+
+<ParamField path="files" type="list[SessionFile]" required>
+  List of non-expired session files
+</ParamField>
+
+<ParamField path="total" type="int" required>
+</ParamField>
+
+<ParamField path="limit" type="int" required>
+</ParamField>
+
+<ParamField path="offset" type="int" required>
+</ParamField>
+
+
+## Module
+
+`notte_sdk.types`

docs/src/sdk-reference/misc/remotefilestorage.mdx

@@ -13,7 +13,7 @@ description: "Base class for storage implementations that handle upload and down
 alist_downloaded_files() -> list[FileInfo]
 ```
 
-List files that have been downloaded into storage by the agents
+List all files in the download_dir
 
 **Returns:**
 
@@ -27,45 +27,45 @@ List files that have been downloaded into storage by the agents
 alist_uploaded_files() -> list[FileInfo]
 ```
 
-List files that have been uploaded to storage
+List all files from the upload_dir
 
 **Returns:**
 
 `list`
 
 ---
 
-### download
+### delete
 
 ```python
-download(file_name: str, local_dir: str, force: bool = False) -> bool
+delete(file_id: str) -> None
 ```
 
-Stores a file that has been downloaded from a website in the current session
+---
+
+### download
+
+```python
+download(file_id: str, local_dir: str = ., force: bool = False) -> str
+```
 
 **Returns:**
 
-`bool`
+`str`
 
 ---
 
-### download_uploaded_file
+### for_session
 
 ```python
-download_uploaded_file(file_name: str, local_dir: str, force: bool = False) -> bool
+for_session(session_id: str) -> RemoteFileStorage
 ```
 
-Downloads a user-uploaded file to the local filesystem without requiring a session attachment
-
-**Parameters:**
-
-- `file_name`: The name of the uploaded file to download.
-- `local_dir`: The directory to download the file to.
-- `force`: Overwrite an existing destination file. Defaults to ``False``; set ``True`` to replace it.
+Bind this storage once, cloning it when another session already owns it
 
 **Returns:**
 
-`bool`
+<Visibility for="humans">[`RemoteFileStorage`](/sdk-reference/misc/remotefilestorage)</Visibility><Visibility for="agents">[`RemoteFileStorage`](/sdk-reference/misc/remotefilestorage.md)</Visibility>
 
 ---
 
@@ -97,6 +97,18 @@ Return LLM instructions to append to the prompt
 
 ---
 
+### list
+
+```python
+list(source: FileSource | str | None = None, limit: int = 100, offset: int = 0) -> SessionFilesPage
+```
+
+**Returns:**
+
+<Visibility for="humans">[`SessionFilesPage`](/sdk-reference/misc/sessionfilespage)</Visibility><Visibility for="agents">[`SessionFilesPage`](/sdk-reference/misc/sessionfilespage.md)</Visibility>
+
+---
+
 ### list_downloaded_files
 
 ```python
@@ -142,22 +154,20 @@ Stores a file from the local path
 ### set_session_id
 
 ```python
-set_session_id(id: str) -> None
+set_session_id(session_id: str) -> None
 ```
 
 ---
 
 ### upload
 
 ```python
-upload(file_path: str, upload_file_name: str | None = None) -> bool
+upload(file_path: str, upload_file_name: str | None = None) -> SessionFile
 ```
 
-Upload a file from your local machine to storage
-
 **Returns:**
 
-`bool`
+<Visibility for="humans">[`SessionFile`](/sdk-reference/misc/sessionfile)</Visibility><Visibility for="agents">[`SessionFile`](/sdk-reference/misc/sessionfile.md)</Visibility>
 
 ---
 

docs/src/sdk-reference/misc/sessionfile.mdx

@@ -0,0 +1,40 @@
+---
+title: "SessionFile"
+description: ""
+---
+
+
+
+## Fields
+
+<ParamField path="id" type="str" required>
+</ParamField>
+
+<ParamField path="session_id" type="str" required>
+</ParamField>
+
+<ParamField path="filename" type="str" required>
+</ParamField>
+
+<ParamField path="mime_type" type="str" required>
+</ParamField>
+
+<ParamField path="size" type="int" required>
+</ParamField>
+
+<ParamField path="checksum" type="str" required>
+</ParamField>
+
+<ParamField path="created_at" type="datetime" required>
+</ParamField>
+
+<ParamField path="expires_at" type="datetime" required>
+</ParamField>
+
+<ParamField path="source" type="FileSource" required>
+</ParamField>
+
+
+## Module
+
+`notte_sdk.types`

docs/src/sdk-reference/misc/sessionfilespage.mdx

@@ -0,0 +1,26 @@
+---
+title: "SessionFilesPage"
+description: ""
+---
+
+
+
+## Fields
+
+<ParamField path="files" type="list[SessionFile]" required>
+  List of non-expired session files
+</ParamField>
+
+<ParamField path="total" type="int" required>
+</ParamField>
+
+<ParamField path="limit" type="int" required>
+</ParamField>
+
+<ParamField path="offset" type="int" required>
+</ParamField>
+
+
+## Module
+
+`notte_sdk.types`

docs/src/sdk-reference/misc/sessionresponse.mdx

@@ -58,10 +58,6 @@ description: ""
 <ParamField path="browser_type" type="Literal['chromium', 'chrome', 'firefox', 'chrome-nightly', 'chrome-turbo']" default="chromium">
 </ParamField>
 
-<ParamField path="use_file_storage" type="bool" default="False">
-  Whether FileStorage was attached to the session.
-</ParamField>
-
 <ParamField path="network_request_bytes" type="int" default="0">
   Total byte usage for network requests.
 </ParamField>

docs/src/sdk-reference/remotefilestorage/alist_downloaded_files.mdx

@@ -1,16 +1,10 @@
 ---
 title: "alist_downloaded_files"
-description: "List files that have been downloaded into storage by the agents"
+description: "List all files in the download_dir"
 ---
 
 
 
-```python
-storage = notte.FileStorage(session_id="<session_id>")
-# list the files that have been downloaded from storage
-files = storage.list_downloaded_files()
-```
-
 
 ## Returns
 

docs/src/sdk-reference/remotefilestorage/alist_uploaded_files.mdx

@@ -1,16 +1,10 @@
 ---
 title: "alist_uploaded_files"
-description: "List files that have been uploaded to storage"
+description: "List all files from the upload_dir"
 ---
 
 
 
-```python
-storage = notte.FileStorage()
-# list the files that have been uploaded to storage
-files = storage.list_uploaded_files()
-```
-
 
 ## Returns
 

docs/src/sdk-reference/remotefilestorage/delete.mdx

@@ -0,0 +1,16 @@
+---
+title: "delete"
+description: "No description available"
+---
+
+
+
+
+## Parameters
+
+<ParamField path="file_id" type="str" required>
+</ParamField>
+
+## Returns
+
+`None`

docs/src/sdk-reference/remotefilestorage/download.mdx

@@ -1,30 +1,22 @@
 ---
 title: "download"
-description: "Stores a file that has been downloaded from a website in the current session"
+description: "No description available"
 ---
 import AgentMdNotice from '/partials/agent-md-notice.mdx';
 
 <AgentMdNotice />
 
-```python
-file_storage = notte.FileStorage("<session_id>")
-# file.pdf has been downloaded by an agent in the session
-# you can download it to your local machine using:
-file_storage.download(file_name="file.pdf", local_dir="<local_download_dir>")
-```
-
-
 ## Parameters
 
-<ParamField path="file_name" type="str" required>
+<ParamField path="file_id" type="str" required>
 </ParamField>
 
-<ParamField path="local_dir" type="str" required>
+<ParamField path="local_dir" type="str" default=".">
 </ParamField>
 
 <ParamField path="force" type="bool" default="False">
 </ParamField>
 
 ## Returns
 
-`bool`
+`str`

docs/src/sdk-reference/remotefilestorage/for_session.mdx

@@ -0,0 +1,16 @@
+---
+title: "for_session"
+description: "Bind this storage once, cloning it when another session already owns it"
+---
+
+
+
+
+## Parameters
+
+<ParamField path="session_id" type="str" required>
+</ParamField>
+
+## Returns
+
+<Visibility for="humans">[`RemoteFileStorage`](/sdk-reference/misc/remotefilestorage)</Visibility><Visibility for="agents">[`RemoteFileStorage`](/sdk-reference/misc/remotefilestorage.md)</Visibility>