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.

Add tool router session deletion (#3679)

Abir Taheer605a7263ab3b
diff --git a/.changeset/great-rivers-delete.md b/.changeset/great-rivers-delete.md
new file mode 100644
index 000000000..2ba8f9cb4
--- /dev/null
+++ b/.changeset/great-rivers-delete.md
@@ -0,0 +1,5 @@
+---
+"@composio/core": patch
+---
+
+Add Tool Router session deletion APIs.
diff --git a/ts/packages/core/src/lib/toolRouterSessionDelete.ts b/ts/packages/core/src/lib/toolRouterSessionDelete.ts
new file mode 100644
index 000000000..c409bf702
--- /dev/null
+++ b/ts/packages/core/src/lib/toolRouterSessionDelete.ts
@@ -0,0 +1,30 @@
+import type ComposioClient from '@composio/client';
+import type { ComposioRequestOptions } from '../types/requestOptions.types';
+import type { ToolRouterSessionDeleteResponse } from '../types/toolRouter.types';
+import { ToolRouterSessionDeleteResponseSchema } from '../types/toolRouter.types';
+import { withCancellation } from '../utils/cancellation';
+
+type ToolRouterSessionDeleteWireResponse = {
+ session_id: string;
+ deleted: true;
+};
+
+export async function deleteToolRouterSession(
+ client: ComposioClient,
+ sessionId: string,
+ requestOptions?: ComposioRequestOptions
+): Promise<ToolRouterSessionDeleteResponse> {
+ const response = await withCancellation(
+ () =>
+ client.delete<ToolRouterSessionDeleteWireResponse>(
+ `/api/v3.1/tool_router/session/${encodeURIComponent(sessionId)}`,
+ requestOptions
+ ),
+ requestOptions?.signal
+ );
+
+ return ToolRouterSessionDeleteResponseSchema.parse({
+ sessionId: response.session_id,
+ deleted: response.deleted,
+ });
+}
diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.ts
index 4f122f176..d70951d0c 100644
--- a/ts/packages/core/src/models/ToolRouter.ts
+++ b/ts/packages/core/src/models/ToolRouter.ts
@@ -29,6 +29,7 @@ import {
ToolRouterMCPServerConfig,
ToolRouterSessionMetadata,
SessionPreset,
+ type ToolRouterSessionDeleteResponse,
} from '../types/toolRouter.types';
import { ToolRouterCreateSessionConfigSchema } from '../types/toolRouter.types';
import {
@@ -55,6 +56,7 @@ import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
import { ToolRouterSession } from './ToolRouterSession';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
+import { deleteToolRouterSession } from '../lib/toolRouterSessionDelete';
import {
assertNoCustomToolSlugsInPreload,
buildCustomToolsMap,
@@ -388,4 +390,17 @@ export class ToolRouter<
metadata
);
}
+
+ /**
+ * Delete a tool router session by ID.
+ *
+ * Deleted sessions immediately stop being retrievable or executable. Deleting
+ * a missing or already-deleted session surfaces the backend 404.
+ */
+ async delete(
+ id: string,
+ requestOptions?: ComposioRequestOptions
+ ): Promise<ToolRouterSessionDeleteResponse> {
+ return deleteToolRouterSession(this.client, id, requestOptions);
+ }
}
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 45150878a..150a07047 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -22,6 +22,7 @@ import {
ToolRouterSessionWarning,
ToolRouterUpdateSessionConfig,
ToolRouterUpdateSessionConfigSchema,
+ type ToolRouterSessionDeleteResponse,
} from '../types/toolRouter.types';
import {
transformSearchResponse,
@@ -71,6 +72,7 @@ import {
import { transformProxyParams } from './proxyParamsTransform';
import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';
+import { deleteToolRouterSession } from '../lib/toolRouterSessionDelete';
const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
@@ -647,6 +649,16 @@ export class ToolRouterSession<
this.warnings = response.warnings ?? [];
}
+ /**
+ * Delete this session.
+ *
+ * Deleted sessions immediately stop being retrievable or executable. Deleting
+ * an already-deleted session surfaces the backend 404.
+ */
+ async delete(requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionDeleteResponse> {
+ return deleteToolRouterSession(this.client, this.sessionId, requestOptions);
+ }
+
// ── Private helpers ──────────────────────────────────────────
/** Check if this session has any custom tools bound. */
diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.ts
index 8b5c753ae..6f6bbf8cc 100644
--- a/ts/packages/core/src/types/toolRouter.types.ts
+++ b/ts/packages/core/src/types/toolRouter.types.ts
@@ -2,6 +2,7 @@ import z from 'zod/v3';
import type { BaseComposioProvider } from '../provider/BaseProvider';
import { SessionMetaToolOptions } from './modifiers.types';
import { ConnectionRequest } from './connectionRequest.types';
+import type { ComposioRequestOptions } from './requestOptions.types';
import type { ToolRouterSessionFilesMount } from '../models/ToolRouterSessionFileMount';
import type { SessionCreateResponse } from '@composio/client/resources/tool-router/session/session.mjs';
import type {
@@ -700,6 +701,16 @@ export type ToolRouterUpdateSessionConfig = z.infer<typeof ToolRouterUpdateSessi
export type ToolRouterSessionUpdateFn = (config: ToolRouterUpdateSessionConfig) => Promise<void>;
+export const ToolRouterSessionDeleteResponseSchema = z.object({
+ sessionId: z.string(),
+ deleted: z.literal(true),
+});
+export type ToolRouterSessionDeleteResponse = z.infer<typeof ToolRouterSessionDeleteResponseSchema>;
+
+export type ToolRouterSessionDeleteFn = (
+ requestOptions?: ComposioRequestOptions
+) => Promise<ToolRouterSessionDeleteResponse>;
+
/** Session type returned by ToolRouter.create() and ToolRouter.use() */
export interface Session<
TToolCollection,
@@ -735,6 +746,8 @@ export interface Session<
execute: ToolRouterSessionExecuteFn;
/** Update the session configuration. Mutates this session in-place. */
update: ToolRouterSessionUpdateFn;
+ /** Delete the session. Deleted sessions are no longer retrievable or executable. */
+ delete: ToolRouterSessionDeleteFn;
/** Proxy an API call through Composio's auth layer using the session's connected account */
proxyExecute: ToolRouterSessionProxyExecuteFn;
/** List custom tools registered in this session, with their final slugs and schemas */
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index 842bb3fcb..1725a05f5 100644
--- a/ts/packages/core/test/models/toolRouter.test.ts
+++ b/ts/packages/core/test/models/toolRouter.test.ts
@@ -40,6 +40,7 @@ const createMockClient = () => ({
baseURL: 'https://api.composio.dev',
apiKey: 'test-api-key',
post: vi.fn(),
+ delete: vi.fn(),
toolRouter: {
session: {
create: vi.fn(),
@@ -3244,6 +3245,41 @@ describe('ToolRouter', () => {
});
});
+ describe('delete method', () => {
+ it('should delete a session by ID and return a camelCase response', async () => {
+ mockClient.delete.mockResolvedValueOnce({
+ session_id: 'trs_delete_123',
+ deleted: true,
+ });
+
+ const result = await toolRouter.delete('trs_delete_123');
+
+ expect(mockClient.delete).toHaveBeenCalledWith(
+ '/api/v3.1/tool_router/session/trs_delete_123',
+ undefined
+ );
+ expect(result).toEqual({
+ sessionId: 'trs_delete_123',
+ deleted: true,
+ });
+ });
+
+ it('should forward request options when deleting by ID', async () => {
+ const requestOptions = { signal: new AbortController().signal };
+ mockClient.delete.mockResolvedValueOnce({
+ session_id: 'trs_delete_123',
+ deleted: true,
+ });
+
+ await toolRouter.delete('trs_delete_123', requestOptions);
+
+ expect(mockClient.delete).toHaveBeenCalledWith(
+ '/api/v3.1/tool_router/session/trs_delete_123',
+ requestOptions
+ );
+ });
+ });
+
describe('use method', () => {
const sessionId = 'session_123';
@@ -3267,6 +3303,7 @@ describe('ToolRouter', () => {
expect(session).toHaveProperty('tools');
expect(session).toHaveProperty('authorize');
expect(session).toHaveProperty('toolkits');
+ expect(session).toHaveProperty('delete');
expect(session.preload.tools).toEqual(['GMAIL_FETCH_EMAILS']);
expect(session.configVersion).toBe(7);
});
@@ -3398,6 +3435,26 @@ describe('ToolRouter', () => {
expect(toolkitsResult.items[0].slug).toBe('gmail');
});
+ it('should return a session with working delete function', async () => {
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
+ mockClient.delete.mockResolvedValueOnce({
+ session_id: sessionId,
+ deleted: true,
+ });
+
+ const session = await toolRouter.use(sessionId);
+ const result = await session.delete();
+
+ expect(mockClient.delete).toHaveBeenCalledWith(
+ '/api/v3.1/tool_router/session/session_123',
+ undefined
+ );
+ expect(result).toEqual({
+ sessionId,
+ deleted: true,
+ });
+ });
+
it('should attach custom tools and expose SDK-preloaded custom schemas', async () => {
const grepTool = createCustomTool('GREP', {
name: 'Grep',