Skip to content

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 Schiabela10288aa87c1
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c484a5770..3fa6637e3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -458,6 +458,16 @@ importers:
specifier: workspace:*
version: link:../../../_utils
+ ts/e2e-tests/runtimes/node/tool-router-pagination:
+ dependencies:
+ '@composio/core':
+ specifier: workspace:*
+ version: link:../../../../packages/core
+ devDependencies:
+ '@e2e-tests/utils':
+ specifier: workspace:*
+ version: link:../../../_utils
+
ts/e2e-tests/runtimes/node/typescript-mjs-import-nodenext:
devDependencies:
'@composio/cli':
diff --git a/ts/docs/api/tool-router.md b/ts/docs/api/tool-router.md
index cb04aaf21..65a13c289 100644
--- a/ts/docs/api/tool-router.md
+++ b/ts/docs/api/tool-router.md
@@ -514,7 +514,7 @@ console.log('Connected:', connectedAccount);
Query the connection state of toolkits in the session.
```typescript
-const { items, nextCursor, totalPages } = await session.toolkits();
+const { items, cursor, totalPages } = await session.toolkits();
for (const toolkit of items) {
console.log(`${toolkit.name} (${toolkit.slug})`);
@@ -527,7 +527,7 @@ for (const toolkit of items) {
// Pagination support
const moreToolkits = await session.toolkits({
- nextCursor: nextCursor,
+ cursor,
limit: 10,
});
@@ -540,7 +540,7 @@ const filteredToolkits = await session.toolkits({
const paginatedFilteredToolkits = await session.toolkits({
toolkits: ['gmail', 'github'],
limit: 5,
- nextCursor: 'cursor_abc',
+ cursor: 'cursor_abc',
});
```
@@ -854,7 +854,7 @@ The response includes:
}
}
],
- nextCursor: 'cursor_abc',
+ cursor: 'cursor_abc',
totalPages: 1
}
```
@@ -984,7 +984,7 @@ interface ToolRouterSession {
authorize: (toolkit: string, options?: { callbackUrl?: string }) => Promise<ConnectionRequest>;
toolkits: (options?: {
toolkits?: string[]; // Filter by specific toolkit slugs
- nextCursor?: string; // Pagination cursor
+ cursor?: string; // Pagination cursor
limit?: number; // Number of items per page
}) => Promise<ToolkitConnectionsDetails>;
files: ToolRouterSessionFilesMount; // List, upload, download, delete files. See tool-router-files.md
diff --git a/ts/e2e-tests/README.md b/ts/e2e-tests/README.md
index f6ccd58f3..f3e2a40ae 100644
--- a/ts/e2e-tests/README.md
+++ b/ts/e2e-tests/README.md
@@ -35,6 +35,7 @@ ts/e2e-tests/
│ ├── mastra-tool-router-zod-v4/ # @composio/mastra Tool Router + Zod v4 tests
│ ├── openai-zod4-compat/ # OpenAI + Zod v4 compatibility tests
│ ├── tool-router-files/ # Tool Router session files (list, upload, download, delete)
+ │ ├── tool-router-pagination/ # Tool Router session.toolkits() cursor pagination
│ └── typescript-mjs-import-nodenext/ # TypeScript moduleResolution: nodenext tests
├── deno/ # Deno runtime tests
│ └── esm-basic/ # ESM compatibility tests via npm: specifier
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example b/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example
new file mode 100644
index 000000000..bfd732909
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example
@@ -0,0 +1 @@
+COMPOSIO_API_KEY=your_composio_api_key
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/README.md b/ts/e2e-tests/runtimes/node/tool-router-pagination/README.md
new file mode 100644
index 000000000..220d1a98b
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/README.md
@@ -0,0 +1,29 @@
+# Tool Router Pagination E2E Test
+
+End-to-end regression test for `session.toolkits()` cursor pagination.
+
+## Prerequisites
+
+- Docker (for running tests in containers)
+- `COMPOSIO_API_KEY` environment variable (any Composio project works)
+
+## Running
+
+```bash
+# From repo root
+COMPOSIO_API_KEY=your_key pnpm test:e2e:node --filter=@e2e-tests/node-tool-router-pagination
+
+# Or from this directory
+COMPOSIO_API_KEY=your_key bun test e2e.test.ts
+```
+
+## What it tests
+
+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.
+
+1. **Page 1** – Call `session.toolkits({ limit: 2 })` against the global toolkit catalog
+2. **Cursor returned** – Assert the response includes a `cursor` (catalog has > 2 toolkits on any project)
+3. **Page 2** – Call `session.toolkits({ limit: 2, cursor })` with the returned cursor
+4. **Advancement** – Assert page 2 slugs do not overlap page 1 slugs
+
+If the cursor is silently stripped, page 2 would equal page 1 and the overlap assertion fails.
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/e2e.test.ts b/ts/e2e-tests/runtimes/node/tool-router-pagination/e2e.test.ts
new file mode 100644
index 000000000..2c7eed538
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/e2e.test.ts
@@ -0,0 +1,59 @@
+/**
+ * Tool Router session.toolkits() cursor pagination E2E test.
+ *
+ * Regression test for PLEN-1886: the SDK was silently dropping the `cursor`
+ * input, so every call returned page 1. This test fails fast if that
+ * behavior ever regresses.
+ *
+ * Project-agnostic: relies on the global toolkit catalog (hundreds of
+ * toolkits), so `limit: 2` always yields multiple pages regardless of
+ * which Composio project is on CI.
+ *
+ * Requires COMPOSIO_API_KEY in environment.
+ */
+
+import { e2e, type E2ETestResult } from '@e2e-tests/utils';
+import { describe, it, expect, beforeAll } from 'bun:test';
+
+declare module 'bun' {
+ interface Env {
+ COMPOSIO_API_KEY: string;
+ }
+}
+
+e2e(import.meta.url, {
+ versions: { node: ['20.19.0', '22.12.0'] },
+ usesFixtures: true,
+ env: {
+ COMPOSIO_API_KEY: Bun.env.COMPOSIO_API_KEY,
+ },
+ defineTests: ({ runFixture }) => {
+ let result: E2ETestResult;
+
+ beforeAll(async () => {
+ result = await runFixture({ filename: 'index.mjs' });
+ }, 120_000);
+
+ describe('session.toolkits pagination', () => {
+ it('exits successfully', () => {
+ expect(result.exitCode).toBe(0);
+ });
+
+ it('page 1 returns items and a cursor', () => {
+ expect(result.stdout).toContain('PAGE1_OK');
+ });
+
+ it('page 2 returns items', () => {
+ expect(result.stdout).toContain('PAGE2_OK');
+ });
+
+ it('pagination advances past page 1', () => {
+ expect(result.stdout).toContain('ADVANCED_OK');
+ });
+
+ it('all operations complete', () => {
+ expect(result.stdout).toContain('ALL_OK');
+ });
+ });
+ },
+});
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs b/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs
new file mode 100644
index 000000000..81b9e034d
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/fixtures/index.mjs
@@ -0,0 +1,54 @@
+/**
+ * E2E fixture: session.toolkits() cursor pagination.
+ *
+ * Reproduces PLEN-1886: if the SDK silently drops the `cursor` input,
+ * page 2 will equal page 1 and the overlap assertion throws.
+ *
+ * Uses the global toolkit catalog (no `toolkits` filter on session create),
+ * so this works against any Composio project.
+ *
+ * Requires COMPOSIO_API_KEY in environment.
+ */
+import { Composio } from '@composio/core';
+
+const apiKey = process.env.COMPOSIO_API_KEY;
+if (!apiKey) {
+ console.error('COMPOSIO_API_KEY is required');
+ process.exit(1);
+}
+
+const composio = new Composio({ apiKey });
+
+async function main() {
+ const userId = `e2e-tool-router-pagination-${Date.now()}`;
+ const session = await composio.create(userId);
+
+ const page1 = await session.toolkits({ limit: 2 });
+ if (page1.items.length !== 2) {
+ throw new Error(`expected 2 items on page 1, got ${page1.items.length}`);
+ }
+ if (!page1.cursor) {
+ throw new Error('expected page 1 to return a cursor — catalog should have > 2 toolkits');
+ }
+ console.log('PAGE1_OK');
+
+ const page2 = await session.toolkits({ limit: 2, cursor: page1.cursor });
+ if (page2.items.length === 0) {
+ throw new Error('expected page 2 to return items');
+ }
+ console.log('PAGE2_OK');
+
+ const page1Slugs = new Set(page1.items.map(t => t.slug));
+ const overlap = page2.items.filter(t => page1Slugs.has(t.slug)).map(t => t.slug);
+ if (overlap.length > 0) {
+ throw new Error(`pagination did not advance — page 2 overlaps page 1 on: ${overlap.join(', ')}`);
+ }
+ console.log('ADVANCED_OK');
+
+ console.log('ALL_OK');
+}
+
+main().catch(err => {
+ console.log('ERROR:', err?.message || err);
+ process.exit(1);
+});
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/package.json b/ts/e2e-tests/runtimes/node/tool-router-pagination/package.json
new file mode 100644
index 000000000..8f6040cdd
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@e2e-tests/node-tool-router-pagination",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "typecheck": "tsc --noEmit",
+ "test:e2e": "bun test e2e.test.ts",
+ "test:e2e:node": "bun test e2e.test.ts"
+ },
+ "dependencies": {
+ "@composio/core": "workspace:*"
+ },
+ "devDependencies": {
+ "@e2e-tests/utils": "workspace:*"
+ }
+}
diff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/tsconfig.json b/ts/e2e-tests/runtimes/node/tool-router-pagination/tsconfig.json
new file mode 100644
index 000000000..3eeaa418d
--- /dev/null
+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/tsconfig.json
@@ -0,0 +1,12 @@
+{
+ "$schema": "https://json.schemastore.org/tsconfig",
+ "compilerOptions": {
+ "target": "es2022",
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "skipLibCheck": true,
+ "noEmit": true
+ },
+ "include": ["e2e.test.ts"]
+}
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 2c73e45ca..4b674a8ac 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -217,7 +217,7 @@ export class ToolRouterSession<
}
const result = await this.client.toolRouter.session.toolkits(this.sessionId, {
- cursor: toolkitOptions.data.nextCursor,
+ cursor: toolkitOptions.data.cursor,
limit: toolkitOptions.data.limit,
toolkits: toolkitOptions.data.toolkits,
is_connected: toolkitOptions.data.isConnected,
@@ -254,7 +254,7 @@ export class ToolRouterSession<
return {
items: toolkitConnectedStates,
- nextCursor: result.next_cursor ?? undefined,
+ cursor: result.next_cursor ?? undefined,
totalPages: result.total_pages,
};
}
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index 1970dd8cd..8011b1d58 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -323,7 +323,7 @@ export const ToolkitConnectionStateSchema = z
export const ToolkitConnectionsDetailsSchema = z.object({
items: z.array(ToolkitConnectionStateSchema),
- nextCursor: z.string().optional(),
+ cursor: z.string().optional(),
totalPages: z.number(),
});
export type ToolkitConnectionsDetails = z.infer<typeof ToolkitConnectionsDetailsSchema>;
@@ -350,7 +350,7 @@ export type ToolRouterAuthorizeFn = (
export const ToolRouterToolkitsOptionsSchema = z.object({
toolkits: z.array(z.string()).optional(),
- nextCursor: z.string().optional(),
+ cursor: z.string().optional(),
limit: z.number().optional(),
isConnected: z.boolean().optional(),
search: z.string().optional(),
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index 51c21f58a..f7da57eb3 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -1650,7 +1650,7 @@ describe('ToolRouter', () => {
});
expect(result).toHaveProperty('items');
- expect(result).toHaveProperty('nextCursor', 'cursor_789');
+ expect(result).toHaveProperty('cursor', 'cursor_789');
expect(result).toHaveProperty('totalPages', 2);
expect(result.items).toHaveLength(3);
});
@@ -1661,7 +1661,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
const result = await session.toolkits({
limit: 10,
- nextCursor: 'cursor_abc',
+ cursor: 'cursor_abc',
});
expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(sessionId, {
@@ -1716,7 +1716,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
const result = await session.toolkits({
limit: 5,
- nextCursor: 'cursor_xyz',
+ cursor: 'cursor_xyz',
toolkits: ['github'],
});
@@ -1736,7 +1736,7 @@ describe('ToolRouter', () => {
const session = await toolRouter.create(userId);
const result = await session.toolkits({
limit: 5,
- nextCursor: 'cursor_xyz',
+ cursor: 'cursor_xyz',
toolkits: ['github', 'gmail'],
isConnected: false,
});
@@ -1841,7 +1841,7 @@ describe('ToolRouter', () => {
const result = await session.toolkits();
expect(result.items).toHaveLength(0);
- expect(result.nextCursor).toBeUndefined();
+ expect(result.cursor).toBeUndefined();
expect(result.totalPages).toBe(0);
});
@@ -1867,15 +1867,15 @@ describe('ToolRouter', () => {
// Fetch first page
const page1 = await session.toolkits({ limit: 2 });
expect(page1.items).toHaveLength(2);
- expect(page1.nextCursor).toBe('cursor_page2');
+ expect(page1.cursor).toBe('cursor_page2');
// Fetch second page
const page2 = await session.toolkits({
limit: 2,
- nextCursor: page1.nextCursor,
+ cursor: page1.cursor,
});
expect(page2.items).toHaveLength(1);
- expect(page2.nextCursor).toBeUndefined();
+ expect(page2.cursor).toBeUndefined();
});
it('should handle API errors', async () => {