Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(core): restore session.toolkits() pagination (#3193)
Alberto Schiabel committed
Apr 16, 2026 at 22:02 UTC
a10288aa87c154d57e960af82346903b01e40eb6
12 files changed
+200
-17
pnpm-lock.yaml
+10
@@ -458,6 +458,16 @@ importers:
458
specifier: workspace:*
459
version: link:../../../_utils
460
461
+ ts/e2e-tests/runtimes/node/tool-router-pagination:
462
+ dependencies:
463
+ '@composio/core':
464
+ specifier: workspace:*
465
+ version: link:../../../../packages/core
466
+ devDependencies:
467
+ '@e2e-tests/utils':
468
+ specifier: workspace:*
469
+ version: link:../../../_utils
470
+
471
ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext:
472
devDependencies:
473
'@composio/cli':
ts/docs/api/tool-router.md
+5
-5
@@ -514,7 +514,7 @@ console.log('Connected:', connectedAccount);
514
Query the connection state of toolkits in the session.
515
516
```typescript
517
-const { items, nextCursor, totalPages } = await session.toolkits();
517
+const { items, cursor, totalPages } = await session.toolkits();
518
519
for (const toolkit of items) {
520
console.log(`${toolkit.name} (${toolkit.slug})`);
@@ -527,7 +527,7 @@ for (const toolkit of items) {
527
528
// Pagination support
529
const moreToolkits = await session.toolkits({
530
- nextCursor: nextCursor,
530
+ cursor,
531
limit: 10,
532
});
533
@@ -540,7 +540,7 @@ const filteredToolkits = await session.toolkits({
540
const paginatedFilteredToolkits = await session.toolkits({
541
toolkits: ['gmail', 'github'],
542
limit: 5,
543
- nextCursor: 'cursor_abc',
543
+ cursor: 'cursor_abc',
544
});
545
```
546
@@ -854,7 +854,7 @@ The response includes:
854
}
855
}
856
],
857
- nextCursor: 'cursor_abc',
857
+ cursor: 'cursor_abc',
858
totalPages: 1
859
}
860
```
@@ -984,7 +984,7 @@ interface ToolRouterSession {
984
authorize: (toolkit: string, options?: { callbackUrl?: string }) => Promise<ConnectionRequest>;
985
toolkits: (options?: {
986
toolkits?: string[]; // Filter by specific toolkit slugs
987
- nextCursor?: string; // Pagination cursor
987
+ cursor?: string; // Pagination cursor
988
limit?: number; // Number of items per page
989
}) => Promise<ToolkitConnectionsDetails>;
990
files: ToolRouterSessionFilesMount; // List, upload, download, delete files. See tool-router-files.md
ts/e2e-tests/README.md
+1
@@ -35,6 +35,7 @@ ts/e2e-tests/
35
│ ├── mastra-tool-router-zod-v4/ # @composio/mastra Tool Router + Zod v4 tests
36
│ ├── openai-zod4-compat/ # OpenAI + Zod v4 compatibility tests
37
│ ├── tool-router-files/ # Tool Router session files (list, upload, download, delete)
38
+ │ ├── tool-router-pagination/ # Tool Router session.toolkits() cursor pagination
39
│ └── typescript-mjs-import-nodenext/ # TypeScript moduleResolution: nodenext tests
40
├── deno/ # Deno runtime tests
41
│ └── esm-basic/ # ESM compatibility tests via npm: specifier
ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example
new
+1
@@ -0,0 +1 @@
1
+COMPOSIO_API_KEY=your_composio_api_key
ts/e2e-tests/runtimes/node/tool-router-pagination/README.md
new
+29
@@ -0,0 +1,29 @@
1
+# Tool Router Pagination E2E Test
2
+
3
+End-to-end regression test for `session.toolkits()` cursor pagination.
4
+
5
+## Prerequisites
6
+
7
+- Docker (for running tests in containers)
8
+- `COMPOSIO_API_KEY` environment variable (any Composio project works)
9
+
10
+## Running
11
+
12
+```bash
13
+# From repo root
14
+COMPOSIO_API_KEY=your_key pnpm test:e2e:node --filter=@e2e-tests/node-tool-router-pagination
15
+
16
+# Or from this directory
17
+COMPOSIO_API_KEY=your_key bun test e2e.test.ts
18
+```
19
+
20
+## What it tests
21
+
22
+Regression coverage for [PLEN-1886](https://linear.app/composio/issue/PLEN-1886): `session.toolkits()` was silently dropping the `cursor` input and always returning page 1.
23
+
24
+1. **Page 1** – Call `session.toolkits({ limit: 2 })` against the global toolkit catalog
25
+2. **Cursor returned** – Assert the response includes a `cursor` (catalog has > 2 toolkits on any project)
26
+3. **Page 2** – Call `session.toolkits({ limit: 2, cursor })` with the returned cursor
27
+4. **Advancement** – Assert page 2 slugs do not overlap page 1 slugs
28
+
29
+If the cursor is silently stripped, page 2 would equal page 1 and the overlap assertion fails.
ts/e2e-tests/runtimes/node/tool-router-pagination/e2e.test.ts
new
+59
@@ -0,0 +1,59 @@
1
+/**
2
+ * Tool Router session.toolkits() cursor pagination E2E test.
3
+ *
4
+ * Regression test for PLEN-1886: the SDK was silently dropping the `cursor`
5
+ * input, so every call returned page 1. This test fails fast if that
6
+ * behavior ever regresses.
7
+ *
8
+ * Project-agnostic: relies on the global toolkit catalog (hundreds of
9
+ * toolkits), so `limit: 2` always yields multiple pages regardless of
10
+ * which Composio project is on CI.
11
+ *
12
+ * Requires COMPOSIO_API_KEY in environment.
13
+ */
14
+
15
+import { e2e, type E2ETestResult } from '@e2e-tests/utils';
16
+import { describe, it, expect, beforeAll } from 'bun:test';
17
+
18
+declare module 'bun' {
19
+ interface Env {
20
+ COMPOSIO_API_KEY: string;
21
+ }
22
+}
23
+
24
+e2e(import.meta.url, {
25
+ versions: { node: ['20.19.0', '22.12.0'] },
26
+ usesFixtures: true,
27
+ env: {
28
+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
29
+ },
30
+ defineTests: ({ runFixture }) => {
31
+ let result: E2ETestResult;
32
+
33
+ beforeAll(async () => {
34
+ result = await runFixture({ filename: 'index.mjs' });
35
+ }, 120_000);
36
+
37
+ describe('session.toolkits pagination', () => {
38
+ it('exits successfully', () => {
39
+ expect(result.exitCode).toBe(0);
40
+ });
41
+
42
+ it('page 1 returns items and a cursor', () => {
43
+ expect(result.stdout).toContain('PAGE1_OK');
44
+ });
45
+
46
+ it('page 2 returns items', () => {
47
+ expect(result.stdout).toContain('PAGE2_OK');
48
+ });
49
+
50
+ it('pagination advances past page 1', () => {
51
+ expect(result.stdout).toContain('ADVANCED_OK');
52
+ });
53
+
54
+ it('all operations complete', () => {
55
+ expect(result.stdout).toContain('ALL_OK');
56
+ });
57
+ });
58
+ },
59
+});
ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs
new
+54
@@ -0,0 +1,54 @@
1
+/**
2
+ * E2E fixture: session.toolkits() cursor pagination.
3
+ *
4
+ * Reproduces PLEN-1886: if the SDK silently drops the `cursor` input,
5
+ * page 2 will equal page 1 and the overlap assertion throws.
6
+ *
7
+ * Uses the global toolkit catalog (no `toolkits` filter on session create),
8
+ * so this works against any Composio project.
9
+ *
10
+ * Requires COMPOSIO_API_KEY in environment.
11
+ */
12
+import { Composio } from '@composio/core';
13
+
14
+const apiKey = process.env.COMPOSIO_API_KEY;
15
+if (!apiKey) {
16
+ console.error('COMPOSIO_API_KEY is required');
17
+ process.exit(1);
18
+}
19
+
20
+const composio = new Composio({ apiKey });
21
+
22
+async function main() {
23
+ const userId = `e2e-tool-router-pagination-${Date.now()}`;
24
+ const session = await composio.create(userId);
25
+
26
+ const page1 = await session.toolkits({ limit: 2 });
27
+ if (page1.items.length !== 2) {
28
+ throw new Error(`expected 2 items on page 1, got ${page1.items.length}`);
29
+ }
30
+ if (!page1.cursor) {
31
+ throw new Error('expected page 1 to return a cursor — catalog should have > 2 toolkits');
32
+ }
33
+ console.log('PAGE1_OK');
34
+
35
+ const page2 = await session.toolkits({ limit: 2, cursor: page1.cursor });
36
+ if (page2.items.length === 0) {
37
+ throw new Error('expected page 2 to return items');
38
+ }
39
+ console.log('PAGE2_OK');
40
+
41
+ const page1Slugs = new Set(page1.items.map(t => t.slug));
42
+ const overlap = page2.items.filter(t => page1Slugs.has(t.slug)).map(t => t.slug);
43
+ if (overlap.length > 0) {
44
+ throw new Error(`pagination did not advance — page 2 overlaps page 1 on: ${overlap.join(', ')}`);
45
+ }
46
+ console.log('ADVANCED_OK');
47
+
48
+ console.log('ALL_OK');
49
+}
50
+
51
+main().catch(err => {
52
+ console.log('ERROR:', err?.message || err);
53
+ process.exit(1);
54
+});
ts/e2e-tests/runtimes/node/tool-router-pagination/package.json
new
+17
@@ -0,0 +1,17 @@
1
+{
2
+ "name": "@e2e-tests/node-tool-router-pagination",
3
+ "version": "0.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "scripts": {
7
+ "typecheck": "tsc --noEmit",
8
+ "test:e2e": "bun test e2e.test.ts",
9
+ "test:e2e:node": "bun test e2e.test.ts"
10
+ },
11
+ "dependencies": {
12
+ "@composio/core": "workspace:*"
13
+ },
14
+ "devDependencies": {
15
+ "@e2e-tests/utils": "workspace:*"
16
+ }
17
+}
ts/e2e-tests/runtimes/node/tool-router-pagination/tsconfig.json
new
+12
@@ -0,0 +1,12 @@
1
+{
2
+ "$schema": "https://json.schemastore.org/tsconfig",
3
+ "compilerOptions": {
4
+ "target": "es2022",
5
+ "module": "esnext",
6
+ "moduleResolution": "bundler",
7
+ "strict": true,
8
+ "skipLibCheck": true,
9
+ "noEmit": true
10
+ },
11
+ "include": ["e2e.test.ts"]
12
+}
ts/packages/core/src/models/ToolRouterSession.ts
+2
-2
@@ -217,7 +217,7 @@ export class ToolRouterSession<
217
}
218
219
const result = await this.client.toolRouter.session.toolkits(this.sessionId, {
220
- cursor: toolkitOptions.data.nextCursor,
220
+ cursor: toolkitOptions.data.cursor,
221
limit: toolkitOptions.data.limit,
222
toolkits: toolkitOptions.data.toolkits,
223
is_connected: toolkitOptions.data.isConnected,
@@ -254,7 +254,7 @@ export class ToolRouterSession<
254
255
return {
256
items: toolkitConnectedStates,
257
- nextCursor: result.next_cursor ?? undefined,
257
+ cursor: result.next_cursor ?? undefined,
258
totalPages: result.total_pages,
259
};
260
}
ts/packages/core/src/types/toolRouter.types.ts
+2
-2
@@ -323,7 +323,7 @@ export const ToolkitConnectionStateSchema = z
323
324
export const ToolkitConnectionsDetailsSchema = z.object({
325
items: z.array(ToolkitConnectionStateSchema),
326
- nextCursor: z.string().optional(),
326
+ cursor: z.string().optional(),
327
totalPages: z.number(),
328
});
329
export type ToolkitConnectionsDetails = z.infer<typeof ToolkitConnectionsDetailsSchema>;
@@ -350,7 +350,7 @@ export type ToolRouterAuthorizeFn = (
350
351
export const ToolRouterToolkitsOptionsSchema = z.object({
352
toolkits: z.array(z.string()).optional(),
353
- nextCursor: z.string().optional(),
353
+ cursor: z.string().optional(),
354
limit: z.number().optional(),
355
isConnected: z.boolean().optional(),
356
search: z.string().optional(),
ts/packages/core/test/models/toolRouter.test.ts
+8
-8
@@ -1650,7 +1650,7 @@ describe('ToolRouter', () => {
1650
});
1651
1652
expect(result).toHaveProperty('items');
1653
- expect(result).toHaveProperty('nextCursor', 'cursor_789');
1653
+ expect(result).toHaveProperty('cursor', 'cursor_789');
1654
expect(result).toHaveProperty('totalPages', 2);
1655
expect(result.items).toHaveLength(3);
1656
});
@@ -1661,7 +1661,7 @@ describe('ToolRouter', () => {
1661
const session = await toolRouter.create(userId);
1662
const result = await session.toolkits({
1663
limit: 10,
1664
- nextCursor: 'cursor_abc',
1664
+ cursor: 'cursor_abc',
1665
});
1666
1667
expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(sessionId, {
@@ -1716,7 +1716,7 @@ describe('ToolRouter', () => {
1716
const session = await toolRouter.create(userId);
1717
const result = await session.toolkits({
1718
limit: 5,
1719
- nextCursor: 'cursor_xyz',
1719
+ cursor: 'cursor_xyz',
1720
toolkits: ['github'],
1721
});
1722
@@ -1736,7 +1736,7 @@ describe('ToolRouter', () => {
1736
const session = await toolRouter.create(userId);
1737
const result = await session.toolkits({
1738
limit: 5,
1739
- nextCursor: 'cursor_xyz',
1739
+ cursor: 'cursor_xyz',
1740
toolkits: ['github', 'gmail'],
1741
isConnected: false,
1742
});
@@ -1841,7 +1841,7 @@ describe('ToolRouter', () => {
1841
const result = await session.toolkits();
1842
1843
expect(result.items).toHaveLength(0);
1844
- expect(result.nextCursor).toBeUndefined();
1844
+ expect(result.cursor).toBeUndefined();
1845
expect(result.totalPages).toBe(0);
1846
});
1847
@@ -1867,15 +1867,15 @@ describe('ToolRouter', () => {
1867
// Fetch first page
1868
const page1 = await session.toolkits({ limit: 2 });
1869
expect(page1.items).toHaveLength(2);
1870
- expect(page1.nextCursor).toBe('cursor_page2');
1870
+ expect(page1.cursor).toBe('cursor_page2');
1871
1872
// Fetch second page
1873
const page2 = await session.toolkits({
1874
limit: 2,
1875
- nextCursor: page1.nextCursor,
1875
+ cursor: page1.cursor,
1876
});
1877
expect(page2.items).toHaveLength(1);
1878
- expect(page2.nextCursor).toBeUndefined();
1878
+ expect(page2.cursor).toBeUndefined();
1879
});
1880
1881
it('should handle API errors', async () => {