Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 296 lines 9.53 KB
Rendered Raw
1 # Tool Router Session Files
2
3 Tool Router sessions include a virtual filesystem mount that enables file storage and retrieval within a session. This is useful for agent workflows, document processing, and tools that need to read or write files. Access the files API via `session.experimental.files` on any Tool Router session.
4
5 > **Related:**
6 > - [Tool Router](./tool-router.md) – Session creation, configuration, and `session.experimental.files` overview
7 > - [Auto Upload and Download](../advanced/auto-upload-download.md) – File handling during tool execution (different feature)
8
9 ## Overview
10
11 Each Tool Router session has a `files` property that provides:
12
13 - **List** – Browse files and directories with cursor-based pagination
14 - **Upload** – Upload files from paths, URLs, native `File` objects, or raw buffers
15 - **Download** – Get presigned download URLs and `RemoteFile` instances
16 - **Delete** – Remove files or directories from the mount
17
18 Files are stored in a virtual filesystem attached to the session. Tools executing in the session can access these files (e.g., at `/mnt/files/` inside the sandbox). The mount ID defaults to `"files"` and can be overridden when using custom mounts.
19
20 ## Quick Start
21
22 ```typescript
23 import { Composio } from '@composio/core';
24
25 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
26 const session = await composio.create('default');
27
28 // Upload a file
29 const file = await session.experimental.files.upload('/path/to/report.pdf');
30 console.log('Uploaded:', file.mountRelativePath);
31
32 // List files
33 const { items, nextCursor } = await session.experimental.files.list({ path: '/' });
34
35 // Download a file
36 const remoteFile = await session.experimental.files.download('report.pdf');
37 const buffer = await remoteFile.buffer();
38 await remoteFile.save('/tmp/report.pdf');
39 ```
40
41 ## List Files
42
43 List files and directories at a path on the session's file mount. Supports cursor-based pagination.
44
45 ### Method Signature
46
47 ```typescript
48 session.experimental.files.list(options?: ToolRouterSessionFilesMountListOptions): Promise<FileListResponse>
49 ```
50
51 ### Options
52
53 | Option | Type | Default | Description |
54 | -------- | ------ | ------- | ---------------------------------------------------------- |
55 | `path` | string | - | Directory path to list. Use `"/"` for root. |
56 | `mountId`| string | `"files"` | The file mount ID. |
57 | `cursor` | string | - | Pagination cursor from the previous response's `nextCursor`. |
58 | `limit` | number | - | Max files per page (1–500). |
59
60 ### Response
61
62 ```typescript
63 interface FileListResponse {
64 items: Array<{
65 lastModified: string; // ISO 8601 timestamp
66 mountRelativePath: string; // e.g. "report.pdf"
67 sandboxMountPrefix: string; // e.g. "/mnt/files"
68 size: number; // File size in bytes
69 }>;
70 nextCursor?: string; // Present when more pages exist
71 }
72 ```
73
74 ### Examples
75
76 ```typescript
77 // List root directory
78 const { items } = await session.experimental.files.list({ path: '/' });
79
80 // List a subdirectory
81 const { items } = await session.experimental.files.list({ path: '/documents' });
82
83 // Paginated listing
84 let result = await session.experimental.files.list({ path: '/', limit: 10 });
85 while (result.nextCursor) {
86 result = await session.experimental.files.list({
87 path: '/',
88 cursor: result.nextCursor,
89 limit: 10,
90 });
91 }
92 ```
93
94 ## Upload Files
95
96 Upload files to the session's mount. Accepts multiple input types: file paths (local or URL), native `File` objects, or raw buffers (`ArrayBuffer` | `Uint8Array`).
97
98 ### Method Signature
99
100 ```typescript
101 session.experimental.files.upload(
102 input: string | File | ArrayBuffer | Uint8Array,
103 options?: ToolRouterSessionFilesMountUploadOptions
104 ): Promise<RemoteFile>
105 ```
106
107 ### Input Types
108
109 | Input Type | Description | Example |
110 | ---------- | ----------- | ------- |
111 | `string` | Local path or HTTP(S) URL | `'/path/to/file.pdf'`, `'https://example.com/file.pdf'` |
112 | `File` | Native browser/Node `File` | `inputElement.files[0]` |
113 | `ArrayBuffer` | Raw binary buffer | `await file.arrayBuffer()` |
114 | `Uint8Array` | Typed array buffer | `new TextEncoder().encode('hello')` |
115
116 ### Upload Options
117
118 | Option | Type | Default | Description |
119 | --------- | ------ | ------- | ----------- |
120 | `remotePath` | string | - | Remote path/filename on the mount. Required when passing a buffer (provides filename; mimetype defaults to `application/octet-stream`). |
121 | `mountId` | string | `"files"` | The file mount ID. |
122 | `mimetype` | string | - | MIME type. Required when passing a buffer unless `remotePath` is provided. Ignored when passing `File` (uses `file.type`). |
123
124 ### How It Works
125
126 1. **Path (string)** – If the path starts with `http://` or `https://`, the file is fetched from the URL. Otherwise it is read from the local filesystem. The filename is derived from the path or URL.
127 2. **File** – Used directly. Filename comes from `file.name` unless `remotePath` is provided.
128 3. **Buffer** – Wrapped in a `File` object. **Either `mimetype` or `remotePath` must be provided.** If only `remotePath` is given, mimetype defaults to `application/octet-stream`. If only `mimetype` is given, a filename is generated from the extension (`upload-{id}.{ext}`).
129
130 ### Examples
131
132 ```typescript
133 // From local path
134 const file = await session.experimental.files.upload('/path/to/report.pdf');
135
136 // From URL
137 const file = await session.experimental.files.upload('https://example.com/document.pdf');
138
139 // From native File (e.g. file input)
140 const file = await session.experimental.files.upload(fileInput.files[0]);
141
142 // From buffer with explicit path and mimetype
143 const buffer = new TextEncoder().encode('{"key": "value"}');
144 const file = await session.experimental.files.upload(buffer, {
145 remotePath: 'data.json',
146 mimetype: 'application/json',
147 });
148
149 // From buffer – mimetype or remotePath required
150 const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, ...]);
151 const file = await session.experimental.files.upload(pngBytes, {
152 remotePath: 'screenshot.png',
153 mimetype: 'image/png',
154 });
155 ```
156
157 ## Download Files
158
159 Get a `RemoteFile` for a file on the mount. The `RemoteFile` provides a presigned download URL and methods to fetch content.
160
161 ### Method Signature
162
163 ```typescript
164 session.experimental.files.download(
165 filePath: string,
166 options?: ToolRouterSessionFilesMountDownloadOptions
167 ): Promise<RemoteFile>
168 ```
169
170 ### Parameters
171
172 - `filePath` – Path of the file on the mount (e.g. `"report.pdf"`, `"output/data.csv"`).
173 - `options.mountId` – Mount ID (default: `"files"`).
174
175 ### RemoteFile
176
177 The returned `RemoteFile` has:
178
179 | Property | Type | Description |
180 | -------- | ---- | ----------- |
181 | `expiresAt` | string | ISO 8601 when the download URL expires |
182 | `mountRelativePath` | string | Path within the mount |
183 | `sandboxMountPrefix` | string | Absolute mount path (e.g. `/mnt/files`) |
184 | `downloadUrl` | string | Presigned URL for downloading |
185 | `filename` | string | Basename of the path |
186
187 Methods:
188
189 - `buffer()` – Fetch content as `Uint8Array`
190 - `text()` – Fetch content as UTF-8 string
191 - `blob()` – Fetch content as `Blob`
192 - `save(path?)` – Download and save to disk (Node.js only; path defaults to `~/.composio/files/`)
193
194 ### Examples
195
196 ```typescript
197 const remoteFile = await session.experimental.files.download('/output/report.pdf');
198
199 // Fetch content
200 const buffer = await remoteFile.buffer();
201 const text = await remoteFile.text();
202
203 // Save to disk (Node.js)
204 await remoteFile.save('/tmp/report.pdf');
205 await remoteFile.save(); // Uses ~/.composio/files/{filename}
206 ```
207
208 ## Delete Files
209
210 Delete a file or directory from the mount.
211
212 ### Method Signature
213
214 ```typescript
215 session.experimental.files.delete(
216 remotePath: string,
217 options?: ToolRouterSessionFilesMountDeleteOptions
218 ): Promise<FileDeleteResponse>
219 ```
220
221 ### Examples
222
223 ```typescript
224 await session.experimental.files.delete('/temp/cache.json');
225 await session.experimental.files.delete('/old-backup', { mountId: 'custom-mount' });
226 ```
227
228 ## Type Reference
229
230 ### ToolRouterSessionFilesMountListOptions
231
232 ```typescript
233 interface ToolRouterSessionFilesMountListOptions {
234 path?: string;
235 mountId?: string; // default: "files"
236 cursor?: string;
237 limit?: number; // 1-500
238 }
239 ```
240
241 ### ToolRouterSessionFilesMountUploadOptions
242
243 ```typescript
244 interface ToolRouterSessionFilesMountUploadOptions {
245 remotePath?: string;
246 mountId?: string; // default: "files"
247 mimetype?: string;
248 }
249 ```
250
251 ### FileListResponse
252
253 ```typescript
254 interface FileListResponse {
255 items: Array<{
256 lastModified: string;
257 mountRelativePath: string;
258 sandboxMountPrefix: string;
259 size: number;
260 }>;
261 nextCursor?: string;
262 }
263 ```
264
265 ### RemoteFile (from download/upload)
266
267 ```typescript
268 interface RemoteFile {
269 readonly expiresAt: string;
270 readonly mountRelativePath: string;
271 readonly sandboxMountPrefix: string;
272 readonly downloadUrl: string;
273 readonly filename: string;
274
275 buffer(): Promise<Uint8Array>;
276 text(): Promise<string>;
277 blob(): Promise<Blob>;
278 save(path?: string): Promise<string>; // Node.js only
279 }
280 ```
281
282 ## Exports
283
284 The following are exported from `@composio/core`:
285
286 - `FileListResponse` – List response type
287 - `ToolRouterSessionFilesMountListOptions` – List options type
288 - `RemoteFile` – File class with `buffer`, `text`, `blob`, `save`
289 - `getExtensionFromMimeType` – Map MIME type to file extension
290
291 ## Platform Support
292
293 - **Node.js** – Full support (paths, `save()`).
294 - **Bun** – Full support.
295 - **Browser** – Paths and `save()` are limited; use `File` or buffers.
296 - **Cloudflare Workers / Edge** – No filesystem; use `File` or buffers only.