Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(core): restore session.toolkits() pagination (#3193)
Alberto Schiabela10288aa87c1
diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 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.mdindex 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 supportconst 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 cursorlimit?: number; // Number of items per page}) => Promise<ToolkitConnectionsDetails>;files: ToolRouterSessionFilesMount; // List, upload, download, delete files. See tool-router-files.mddiff --git a/ts/e2e-tests/README.md b/ts/e2e-tests/README.mdindex 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: specifierdiff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example b/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.examplenew file mode 100644index 000000000..bfd732909--- /dev/null+++ b/ts/e2e-tests/runtimes/node/tool-router-pagination/.env.example@@ -0,0 +1 @@+COMPOSIO_API_KEY=your_composio_api_keydiff --git a/ts/e2e-tests/runtimes/node/tool-router-pagination/README.md b/ts/e2e-tests/runtimes/node/tool-router-pagination/README.mdnew file mode 100644index 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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.tsindex 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 = zexport 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.tsindex 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 pageconst 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 pageconst 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 () => {