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.

34.6 KB
Raw Blame
import { telemetry } from '../telemetry/Telemetry';
import { Composio as ComposioClient, BadRequestError } from '@composio/client';
import type { BaseComposioProvider } from '../provider/BaseProvider';
import type { ComposioConfig } from '../composio';
import type { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
import { ComposioRequestCancelledError } from '../errors/SDKErrors';
import {
  ToolRouterMCPServerConfig,
  SessionExperimental,
  ToolRouterToolkitsOptions,
  ToolRouterToolkitsOptionsSchema,
  ToolRouterSessionSearchResponse,
  ToolRouterSessionSearchResponseSchema,
  ToolRouterSessionExecuteResponse,
  ToolRouterSessionExecuteResponseSchema,
  ToolRouterSessionProxyExecuteResponse,
  ToolRouterSessionExecuteOptions,
  ToolRouterSessionMetadata,
  ToolRouterSessionPreloadConfig,
  ToolRouterSessionWorkbenchConfig,
  ToolRouterSessionWarning,
  ToolRouterUpdateSessionConfig,
  ToolRouterUpdateSessionConfigSchema,
  ToolRouterSessionListConfigHistoryOptions,
  ToolRouterSessionListConfigHistoryOptionsSchema,
  type ToolRouterSessionListConfigHistoryResponse,
  type ToolRouterSessionDeleteResponse,
} from '../types/toolRouter.types';
import {
  transformSearchResponse,
  transformExecuteResponse,
} from '../utils/transformers/toolRouterResponseTransform';
import { SessionMetaToolOptions } from '../types/modifiers.types';
import { ConnectionRequest } from '../types/connectionRequest.types';
import { createConnectionRequest } from './ConnectionRequest';
import {
  ConnectedAccountExperimentalSchema,
  ConnectedAccountStatuses,
  ConnectedAccountType,
  ConnectedAccountAclConfig,
} from '../types/connectedAccounts.types';
import { ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT, serializeExperimentalForWire } from './Experimental';
import { z } from 'zod/v3';
import { transform } from '../utils/transform';
import { ToolkitConnectionStateSchema } from '../types/toolRouter.types';
import {
  ComposioAclOnlyForSharedError,
  ComposioInvalidModifierError,
  ValidationError,
} from '../errors';
import { Tools } from './Tools';
import { ToolRouterSessionFilesMount } from './ToolRouterSessionFileMount';
import type {
  CustomToolsMap,
  CustomToolsMapEntry,
  SessionContext,
  RegisteredCustomTool,
  RegisteredCustomToolkit,
} from '../types/customTool.types';
import { ToolSchema, type Tool, type ToolExecuteResponse } from '../types/tool.types';
import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
import type {
  SessionExecuteParams,
  SessionLinkParams,
  SessionSearchParams,
} from '@composio/client/resources/tool-router/session/session.mjs';
import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
import { SessionContextImpl } from './SessionContext';
import {
  assertUnambiguousCustomToolSlug,
  findCustomTool,
  executeCustomTool,
} from './customToolExecution';
import {
  findCustomToolMapEntryByFinalSlug,
  findCustomToolMapEntryByToolkitAndOriginalSlug,
} from './CustomTool';
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 =
  '[Direct tool - call directly, no search needed beforehand.]';

/**
 * Options accepted by {@link ToolRouterSession.authorize}.
 *
 * Validated at the SDK boundary so callers get clear `ValidationError`s for
 * oversized ACL lists or invalid `userId`s — same caps as the equivalent
 * `composio.connectedAccounts.link()` path (≤1000 entries per list, each
 * `userId` 1..256 characters).
 */
const AuthorizeOptionsSchema = z.object({
  callbackUrl: z.string().optional(),
  alias: z.string().optional(),
  experimental: ConnectedAccountExperimentalSchema.optional(),
});

/**
 * A Composio session — the object returned by `composio.sessions.create(...)`
 * and `composio.sessions.use(...)` (also reachable via the top-level
 * `composio.create(...)` / `composio.use(...)` aliases).
 *
 * This is the canonical session surface. Use it to fetch session-scoped tools,
 * authorize toolkits, search, and execute tools. The public return type is
 * `Session` (with `mcp` surfaced, returned when `{ mcp: true }` is passed) or
 * `SessionWithoutMcp` (the default, with `mcp` omitted from the type); this
 * class is the concrete runtime form behind both.
 *
 * @see {@link Sessions} for the `composio.sessions` factory.
 */
export class ToolRouterSession<
  TToolCollection,
  TTool,
  TProvider extends BaseComposioProvider<TToolCollection, TTool, unknown>,
> {
  public readonly sessionId: string;
  /** Hosted MCP endpoint (`session.mcp.url` / `session.mcp.headers`). Exists on every session at runtime, but only surfaced in the type when the session is created with `{ mcp: true }` (which returns `Session`); the default `SessionWithoutMcp` omits `mcp`, so MCP is an explicit opt-in. See https://docs.composio.dev/docs/sessions-via-mcp */
  public readonly mcp: ToolRouterMCPServerConfig;
  public readonly experimental: SessionExperimental;
  public preload: ToolRouterSessionPreloadConfig;
  /** Resolved sandbox (code-execution) config returned by the API. `enable` defaults to `true` server-side. */
  public sandbox?: ToolRouterSessionWorkbenchConfig;
  public configVersion?: number;
  public warnings: ToolRouterSessionWarning[];
  private readonly preloadedCustomToolSlugs: string[];
  private readonly inlineCustomToolsPayload: ToolRouterSessionMetadata['inlineCustomToolsPayload'];

  /** Singleton session context — shared across all custom tool executions */
  private readonly sessionContext?: SessionContext;

  constructor(
    private readonly client: ComposioClient,
    private readonly config: ComposioConfig<TProvider> | undefined,
    sessionId: string,
    mcp: ToolRouterMCPServerConfig,
    experimentalOverrides?: Pick<SessionExperimental, 'assistivePrompt'>,
    private readonly customToolsMap?: CustomToolsMap,
    private readonly userId?: string,
    metadata?: ToolRouterSessionMetadata
  ) {
    if (customToolsMap && !userId) {
      throw new Error('userId is required when custom tools are bound to a session.');
    }
    this.sessionId = sessionId;
    this.mcp = mcp;
    this.experimental = {
      assistivePrompt: experimentalOverrides?.assistivePrompt,
      files: new ToolRouterSessionFilesMount(client, sessionId),
    };
    this.preload = metadata?.preload ?? { tools: [] };
    this.sandbox = metadata?.workbench;
    this.configVersion = metadata?.configVersion;
    this.warnings = metadata?.warnings ?? [];
    this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];
    this.inlineCustomToolsPayload = metadata?.inlineCustomToolsPayload;

    // Create singleton session context if custom tools are bound
    if (customToolsMap && userId) {
      this.sessionContext = new SessionContextImpl(
        client,
        userId,
        sessionId,
        customToolsMap,
        this.inlineCustomToolsPayload
      );
    }

    telemetry.instrument(this, 'ToolRouterSession');
  }

  /**
   * Resolved sandbox config for the session.
   *
   * @deprecated Use `session.sandbox` instead. `workbench` is a backwards-compatible alias and will be removed in a future release.
   */
  public get workbench(): ToolRouterSessionWorkbenchConfig | undefined {
    return this.sandbox;
  }

  public set workbench(value: ToolRouterSessionWorkbenchConfig | undefined) {
    this.sandbox = value;
  }

  /**
   * Get the tools available in the session, formatted for your AI framework.
   * Requires a provider to be configured in the Composio constructor.
   *
   * When custom tools are bound to the session, execution of COMPOSIO_MULTI_EXECUTE_TOOL
   * is intercepted: local tools are executed in-process, remote tools are sent to the backend.
   */
  async tools(
    modifiers?: SessionMetaToolOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ReturnType<TProvider['wrapTools']>> {
    const ToolsModel = new Tools<TToolCollection, TTool, TProvider>(this.client, this.config);
    const rawTools = await ToolsModel.getRawToolRouterSessionTools(
      this.sessionId,
      undefined,
      requestOptions
    );
    const tools = await this.applySchemaModifier(rawTools, modifiers?.modifySchema);
    const sessionTools = await this.addPreloadedCustomTools(tools, modifiers);
    const rawToolBySlug = new Map(rawTools.map(tool => [tool.slug.toUpperCase(), tool]));

    if (this.hasCustomTools()) {
      // Create an execute function that splits local/remote tools in COMPOSIO_MULTI_EXECUTE_TOOL
      const routingExecuteFn = async (
        toolSlug: string,
        input: Record<string, unknown>
      ): Promise<ToolExecuteResponse> => {
        if (toolSlug === COMPOSIO_MULTI_EXECUTE_TOOL) {
          return this.routeMultiExecute(input, ToolsModel, rawTools, modifiers);
        }
        const customTool = findCustomTool(this.customToolsMap, toolSlug);
        if (customTool) {
          return executeCustomTool(customTool, input, this.sessionContext!);
        }
        assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
        return this.executeBackendSessionTool(
          ToolsModel,
          toolSlug,
          input,
          modifiers,
          rawToolBySlug.get(toolSlug.toUpperCase())
        );
      };

      if (!this.config?.provider) {
        throw new Error(
          'A provider is required when using custom tools with session.tools(). ' +
            'Pass a provider in the Composio constructor.'
        );
      }
      return this.config.provider.wrapTools(sessionTools, routingExecuteFn) as ReturnType<
        TProvider['wrapTools']
      >;
    }

    // Standard path (no local tools)
    const wrappedTools = modifiers?.modifySchema
      ? ToolsModel.wrapToolsForToolRouter(this.sessionId, sessionTools, modifiers, rawTools)
      : ToolsModel.wrapToolsForToolRouter(this.sessionId, sessionTools, modifiers);
    return wrappedTools as ReturnType<TProvider['wrapTools']>;
  }

  private async applySchemaModifier(
    tools: Tool[],
    modifier?: SessionMetaToolOptions['modifySchema']
  ): Promise<Tool[]> {
    if (!modifier) {
      return tools;
    }
    if (typeof modifier !== 'function') {
      throw new ComposioInvalidModifierError('Invalid schema modifier. Not a function.');
    }
    return Promise.all(
      tools.map(tool =>
        modifier({
          toolSlug: tool.slug,
          toolkitSlug: tool.toolkit?.slug ?? 'unknown',
          schema: ToolSchema.parse(tool),
        })
      )
    );
  }

  private async addPreloadedCustomTools(
    tools: Tool[],
    modifiers?: SessionMetaToolOptions
  ): Promise<Tool[]> {
    const customTools = await this.getPreloadedCustomToolSchemas(modifiers);
    if (!customTools.length) {
      return tools;
    }

    const existingSlugs = new Set(tools.map(tool => tool.slug.toUpperCase()));
    const appendedTools = customTools.filter(tool => !existingSlugs.has(tool.slug.toUpperCase()));
    if (!appendedTools.length) {
      return tools;
    }

    return [...tools, ...appendedTools];
  }

  private async getPreloadedCustomToolSchemas(modifiers?: SessionMetaToolOptions): Promise<Tool[]> {
    if (!this.customToolsMap || !this.preloadedCustomToolSlugs.length) {
      return [];
    }

    const tools: Tool[] = [];
    for (const slug of this.preloadedCustomToolSlugs) {
      const entry = findCustomToolMapEntryByFinalSlug(this.customToolsMap, slug);
      if (!entry) {
        continue;
      }

      let tool = this.customToolEntryToTool(entry);
      if (modifiers?.modifySchema) {
        tool = await modifiers.modifySchema({
          toolSlug: tool.slug,
          toolkitSlug: tool.toolkit?.slug ?? 'custom',
          schema: tool,
        });
      }
      tools.push(tool);
    }
    return tools;
  }

  private customToolEntryToTool(entry: CustomToolsMapEntry): Tool {
    const toolkitSlug = entry.toolkit ?? 'custom';
    const customToolkit = this.customToolsMap?.toolkits?.find(
      toolkit => toolkit.slug.toLowerCase() === toolkitSlug.toLowerCase()
    );
    const toolkitName = customToolkit?.name ?? entry.toolkit ?? 'Custom';

    return {
      slug: entry.finalSlug,
      name: entry.handle.name,
      description: `${DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX}\n${entry.handle.description}`,
      inputParameters: entry.handle.inputSchema as Tool['inputParameters'],
      outputParameters: entry.handle.outputSchema as Tool['outputParameters'],
      tags: [],
      toolkit: {
        slug: toolkitSlug,
        name: toolkitName,
      },
      isDeprecated: false,
      availableVersions: [],
      scopes: [],
      isNoAuth: !entry.handle.extendsToolkit,
    };
  }

  /**
   * List all custom tools registered in this session.
   * Returns tools with their final slugs, schemas, and resolved toolkit.
   *
   * @param options.toolkit - Filter by toolkit slug (e.g. 'gmail', 'DEV_TOOLS')
   * @returns Array of registered custom tools
   */
  customTools(options?: { toolkit?: string }): RegisteredCustomTool[] {
    if (!this.customToolsMap) return [];

    const entries = Array.from(this.customToolsMap.byFinalSlug.values());
    const filtered = options?.toolkit
      ? entries.filter(e => e.toolkit?.toLowerCase() === options.toolkit!.toLowerCase())
      : entries;

    return filtered.map(entry => ({
      slug: entry.finalSlug,
      name: entry.handle.name,
      description: entry.handle.description,
      toolkit: entry.toolkit,
      inputSchema: entry.handle.inputSchema,
      outputSchema: entry.handle.outputSchema,
    }));
  }

  /**
   * List all custom toolkits registered in this session.
   * Returns toolkits with their tools showing final slugs.
   *
   * @returns Array of registered custom toolkits
   */
  customToolkits(): RegisteredCustomToolkit[] {
    const toolkits = this.customToolsMap?.toolkits;
    if (!toolkits?.length) return [];

    return toolkits.map(tk => ({
      slug: tk.slug,
      name: tk.name,
      description: tk.description,
      tools: tk.tools.map(tool => {
        // Look up by toolkit + original slug so toolkits can safely reuse common names
        // like VERSION, CLICK, or SEARCH without losing the backend-assigned final slug.
        // Only trust a bare alias that belongs to this toolkit.
        const bare = this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());
        const entry =
          findCustomToolMapEntryByToolkitAndOriginalSlug(this.customToolsMap, tk.slug, tool.slug) ??
          (bare?.toolkit && bare.toolkit.toLowerCase() === tk.slug.toLowerCase()
            ? bare
            : undefined);
        return {
          slug: entry?.finalSlug ?? tool.slug,
          name: tool.name,
          description: tool.description,
          toolkit: tk.slug,
          inputSchema: tool.inputSchema,
          outputSchema: tool.outputSchema,
        };
      }),
    }));
  }

  /**
   * Initiate an authorization flow for a toolkit.
   * Returns a ConnectionRequest with a redirect URL for the user.
   *
   * Pass `experimental: { accountType: 'SHARED', aclConfigForShared }` to
   * create a SHARED connection with a per-user ACL in one flow. Default
   * behaviour (omit the block) creates a PRIVATE connection.
   *
   * Experimental — shape may change in future releases.
   *
   * `aclConfigForShared` is validated against the same caps as
   * `composio.connectedAccounts.link()` (≤1000 entries per list, each
   * `userId` 1..256 characters). Invalid input throws `ValidationError`
   * at the SDK boundary.
   */
  async authorize(
    toolkit: string,
    options?: {
      callbackUrl?: string;
      alias?: string;
      experimental?: {
        accountType?: ConnectedAccountType;
        aclConfigForShared?: ConnectedAccountAclConfig;
      };
    },
    requestOptions?: ComposioRequestOptions
  ): Promise<ConnectionRequest> {
    const parsedAuthorizeOptions = AuthorizeOptionsSchema.safeParse(options ?? {});
    if (!parsedAuthorizeOptions.success) {
      throw new ValidationError('Failed to parse tool router authorize options', {
        cause: parsedAuthorizeOptions.error,
      });
    }
    const opts = parsedAuthorizeOptions.data;
    const experimentalWire = serializeExperimentalForWire(opts.experimental);
    const body: SessionLinkParams = {
      toolkit,
      ...(opts.callbackUrl !== undefined && { callback_url: opts.callbackUrl }),
      ...(opts.alias !== undefined && { alias: opts.alias }),
      ...(experimentalWire !== undefined && {
        experimental: experimentalWire as SessionLinkParams.Experimental,
      }),
    };

    let response;
    try {
      response = await withCancellation(
        () => this.client.toolRouter.session.link(this.sessionId, body, requestOptions),
        requestOptions?.signal
      );
    } catch (error) {
      // Caller-initiated cancellation must surface as the typed error,
      // not get remapped to a domain error below.
      if (error instanceof ComposioRequestCancelledError) {
        throw error;
      }
      // The server rejects ACL on PRIVATE connections — surface that as a
      // typed error mirroring `composio.connectedAccounts.link()`.
      if (
        error instanceof BadRequestError &&
        typeof error.message === 'string' &&
        error.message.includes(ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT)
      ) {
        throw new ComposioAclOnlyForSharedError(error.message, { cause: error });
      }
      throw error;
    }

    return createConnectionRequest(
      this.client,
      response.connected_account_id,
      ConnectedAccountStatuses.INITIATED,
      response.redirect_url
    );
  }

  /**
   * Query the connection state of toolkits in the session.
   * Supports pagination and filtering by toolkit slugs.
   */
  async toolkits(options?: ToolRouterToolkitsOptions, requestOptions?: ComposioRequestOptions) {
    const toolkitOptions = ToolRouterToolkitsOptionsSchema.safeParse(options ?? {});
    if (!toolkitOptions.success) {
      throw new ValidationError('Failed to parse toolkits options', {
        cause: toolkitOptions.error,
      });
    }

    const toolkitsParams = {
      cursor: toolkitOptions.data.cursor,
      limit: toolkitOptions.data.limit,
      toolkits: toolkitOptions.data.toolkits,
      is_connected: toolkitOptions.data.isConnected,
      search: toolkitOptions.data.search,
    };
    const result = await withCancellation(
      () => this.client.toolRouter.session.toolkits(this.sessionId, toolkitsParams, requestOptions),
      requestOptions?.signal
    );

    const toolkitConnectedStates = result.items.map(item => {
      const connectedState = transform(item)
        .with(ToolkitConnectionStateSchema)
        .using(item => ({
          slug: item.slug,
          name: item.name,
          logo: item.meta?.logo,
          isNoAuth: item.is_no_auth,
          connection: item.is_no_auth
            ? undefined
            : {
                isActive: item.connected_account?.status === 'ACTIVE',
                authConfig: item.connected_account && {
                  id: item.connected_account?.auth_config.id,
                  mode: item.connected_account?.auth_config.auth_scheme,
                  isComposioManaged: item.connected_account?.auth_config.is_composio_managed,
                },
                connectedAccount: item.connected_account
                  ? {
                      id: item.connected_account.id,
                      status: item.connected_account.status,
                    }
                  : undefined,
              },
        }));
      return connectedState;
    });

    return {
      items: toolkitConnectedStates,
      cursor: result.next_cursor ?? undefined,
      totalPages: result.total_pages,
    };
  }

  /**
   * Search for tools by semantic use case.
   * Returns relevant tools for the given query with schemas and guidance.
   */
  async search(
    params: {
      query: string;
      toolkits?: string[];
    },
    requestOptions?: ComposioRequestOptions
  ): Promise<ToolRouterSessionSearchResponse> {
    const experimental = inlineCustomToolsExperimental<SessionSearchParams.Experimental>(
      this.inlineCustomToolsPayload
    );
    const searchParams = {
      queries: [{ use_case: params.query }],
      ...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
      ...(experimental ? { experimental } : {}),
    };
    const response = await withCancellation(
      () => this.client.toolRouter.session.search(this.sessionId, searchParams, requestOptions),
      requestOptions?.signal
    );
    const transformed = transformSearchResponse(response);
    return ToolRouterSessionSearchResponseSchema.parse(transformed);
  }

  /**
   * Execute a tool within the session.
   *
   * For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the
   * original slug (e.g. "GREP") when that original slug is unique across
   * the session's custom tools and toolkits. Custom tools are executed
   * in-process; remote tools are sent to the Composio backend.
   *
   * @param toolSlug - The tool slug to execute
   * @param arguments_ - Optional tool arguments
   * @param options - Optional execution options
   * @param options.account - Account identifier for direct app tool execution in multi-account sessions. Helper/meta tools either ignore this top-level field or define their own account-selection fields.
   * @returns The tool execution result
   */
  async execute(
    toolSlug: string,
    arguments_?: Record<string, unknown>,
    options?: ToolRouterSessionExecuteOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ToolRouterSessionExecuteResponse> {
    // Check if this is a local tool (by original or final slug)
    const entry = findCustomTool(this.customToolsMap, toolSlug);
    if (entry) {
      // Bail before invoking user code if the caller has already aborted.
      // Custom-tool execution is *cooperative*: long-running user code
      // won't observe later aborts unless the user wires the signal into
      // their own fetch/work — we pass it through via the executeCustomTool
      // session context so they can.
      if (requestOptions?.signal?.aborted) {
        throw new ComposioRequestCancelledError();
      }
      const result = await executeCustomTool(entry, arguments_ ?? {}, this.sessionContext!, {
        signal: requestOptions?.signal,
      });
      return {
        data: result.data,
        error: result.error,
        logId: '',
      };
    }
    assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);

    // Remote execution
    const executeParams: SessionExecuteParams = {
      tool_slug: toolSlug,
      arguments: arguments_ ?? {},
    };
    if (options?.account) {
      executeParams.account = options.account;
    }
    const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
      this.inlineCustomToolsPayload
    );
    if (experimental) {
      executeParams.experimental = experimental;
    }

    const response = await withCancellation(
      () => this.client.toolRouter.session.execute(this.sessionId, executeParams, requestOptions),
      requestOptions?.signal
    );
    const transformed = transformExecuteResponse(response);
    return ToolRouterSessionExecuteResponseSchema.parse(transformed);
  }

  /**
   * Proxy an API call through Composio's auth layer using the session's connected account.
   * The backend resolves the connected account from the toolkit within the session.
   *
   * @param params - Proxy request parameters (toolkit, endpoint, method, body, headers/query params)
   * @returns The proxied API response with status, data, headers
   */
  async proxyExecute(
    params: SessionProxyExecuteParams,
    requestOptions?: ComposioRequestOptions
  ): Promise<ToolRouterSessionProxyExecuteResponse> {
    const validated = SessionProxyExecuteParamsSchema.safeParse(params);
    if (!validated.success) {
      throw new ValidationError('Invalid proxy execute parameters', { cause: validated.error });
    }

    const clientParams = transformProxyParams(validated.data);
    const response = await withCancellation(
      () =>
        this.client.toolRouter.session.proxyExecute(this.sessionId, clientParams, requestOptions),
      requestOptions?.signal
    );

    return {
      status: response.status,
      data: response.data,
      headers: response.headers,
      ...(response.binary_data
        ? {
            binaryData: {
              contentType: response.binary_data.content_type,
              size: response.binary_data.size,
              url: response.binary_data.url,
              expiresAt: response.binary_data.expires_at,
            },
          }
        : {}),
    };
  }

  /**
   * Partially update the session configuration.
   * Only the fields provided will be changed; omitted fields are preserved.
   * Mutates this session's `configVersion`, `preload`, and `warnings` in-place.
   */
  async update(
    config: ToolRouterUpdateSessionConfig,
    requestOptions?: ComposioRequestOptions
  ): Promise<void> {
    const parsed = ToolRouterUpdateSessionConfigSchema.parse(config);
    const params = transformToolRouterUpdateParams(parsed);
    const response = await withCancellation(
      () => this.client.toolRouter.session.patch(this.sessionId, params, requestOptions),
      requestOptions?.signal
    );
    this.configVersion = response.config_version;
    this.preload = response.config.preload;
    this.sandbox = response.config.workbench;
    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);
  }

  /**
   * Page through this session's configuration history, newest first. The
   * first page starts with the live config (`isCurrent: true`); every
   * `session.update()` archives the previous version as a history row.
   *
   * @param options - Optional `cursor` and `limit` (max 100)
   * @returns The config versions on this page plus pagination info
   * @throws {ValidationError} If the options fail validation
   *
   * @example
   * ```typescript
   * const { items, nextCursor } = await session.listConfigHistory({ limit: 10 });
   * console.log(items[0].version, items[0].isCurrent); // e.g. 3, true
   * console.log(items[1].config.toolkits);
   * ```
   */
  async listConfigHistory(
    options?: ToolRouterSessionListConfigHistoryOptions,
    requestOptions?: ComposioRequestOptions
  ): Promise<ToolRouterSessionListConfigHistoryResponse> {
    const parsedOptions = ToolRouterSessionListConfigHistoryOptionsSchema.safeParse(options ?? {});
    if (!parsedOptions.success) {
      throw new ValidationError('Failed to parse config history options', {
        cause: parsedOptions.error,
      });
    }
    const query = {
      cursor: parsedOptions.data.cursor,
      limit: parsedOptions.data.limit,
    };
    const response = await withCancellation(
      () => this.client.toolRouter.session.configHistory(this.sessionId, query, requestOptions),
      requestOptions?.signal
    );
    return {
      items: response.items.map(item => ({
        version: item.version,
        createdAt: item.created_at,
        isCurrent: item.is_current,
        config: item.config,
      })),
      nextCursor: response.next_cursor ?? null,
      totalPages: response.total_pages,
      currentPage: response.current_page,
      totalItems: response.total_items,
    };
  }

  // ── Private helpers ──────────────────────────────────────────

  /** Check if this session has any custom tools bound. */
  private hasCustomTools(): boolean {
    return (this.customToolsMap?.byFinalSlug.size ?? 0) > 0;
  }

  private executeBackendSessionTool(
    ToolsModel: Tools<TToolCollection, TTool, TProvider>,
    toolSlug: string,
    input: Record<string, unknown>,
    modifiers?: SessionMetaToolOptions,
    tool?: Tool
  ): Promise<ToolExecuteResponse> {
    const body = { sessionId: this.sessionId, arguments: input };
    const experimental = inlineCustomToolsExperimental<SessionExecuteParams.Experimental>(
      this.inlineCustomToolsPayload
    );
    if (experimental) {
      return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool, { experimental });
    }
    return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool);
  }

  /** Parse an individual tool item from COMPOSIO_MULTI_EXECUTE_TOOL's tools array */
  private parseToolItem(item: unknown): { tool_slug: string; arguments: Record<string, unknown> } {
    if (typeof item !== 'object' || item === null) {
      return { tool_slug: '', arguments: {} };
    }
    const obj = item as Record<string, unknown>;
    return {
      tool_slug: String(obj.tool_slug ?? ''),
      arguments: (obj.arguments as Record<string, unknown> | undefined) ?? {},
    };
  }

  /**
   * Route a COMPOSIO_MULTI_EXECUTE_TOOL call.
   * Splits the tools[] array into local and remote, executes each appropriately,
   * and merges results preserving original order.
   */
  private async routeMultiExecute(
    input: Record<string, unknown>,
    ToolsModel: Tools<TToolCollection, TTool, TProvider>,
    tools: Tool[],
    modifiers?: SessionMetaToolOptions
  ): Promise<ToolExecuteResponse> {
    const multiExecuteTool = tools.find(tool => tool.slug === COMPOSIO_MULTI_EXECUTE_TOOL);
    const toolItems = input.tools as unknown[];
    if (!Array.isArray(toolItems) || toolItems.length === 0) {
      // Fallback: send to backend as-is
      return this.executeBackendSessionTool(
        ToolsModel,
        COMPOSIO_MULTI_EXECUTE_TOOL,
        input,
        modifiers,
        multiExecuteTool
      );
    }

    const parsed = toolItems.map(item => this.parseToolItem(item));

    // Partition into local (with resolved entry) and remote
    const localItems: Array<{ index: number; entry: CustomToolsMapEntry }> = [];
    const remoteIndices: number[] = [];
    for (let i = 0; i < parsed.length; i++) {
      const entry = findCustomTool(this.customToolsMap, parsed[i].tool_slug);
      if (entry) {
        localItems.push({ index: i, entry });
      } else {
        assertUnambiguousCustomToolSlug(this.customToolsMap, parsed[i].tool_slug);
        remoteIndices.push(i);
      }
    }

    // All remote — just forward entire payload
    if (localItems.length === 0) {
      return this.executeBackendSessionTool(
        ToolsModel,
        COMPOSIO_MULTI_EXECUTE_TOOL,
        input,
        modifiers,
        multiExecuteTool
      );
    }

    // Execute local tools in parallel (shared singleton context)
    const ctx = this.sessionContext!;
    const localPromises = localItems.map(async ({ index, entry }) => {
      const result = await executeCustomTool(entry, parsed[index].arguments, ctx);
      return { index, result };
    });

    // Execute remote tools via backend in parallel with local
    let remotePromise: Promise<ToolExecuteResponse> | undefined;
    if (remoteIndices.length > 0) {
      const remoteToolItems = remoteIndices.map(i => toolItems[i]);
      const remoteInput = { ...input, tools: remoteToolItems };
      remotePromise = this.executeBackendSessionTool(
        ToolsModel,
        COMPOSIO_MULTI_EXECUTE_TOOL,
        remoteInput,
        modifiers,
        multiExecuteTool
      );
    }

    const [localResults, remoteOutcome] = await Promise.all([
      Promise.all(localPromises),
      remotePromise
        ? remotePromise.then(result => ({ result })).catch(error => ({ error }))
        : undefined,
    ]);

    const remoteTransportFailed = !!remoteOutcome && 'error' in remoteOutcome;
    const remoteTransportError = remoteTransportFailed ? remoteOutcome.error : null;
    const remoteErrorMessage = remoteTransportFailed
      ? (remoteTransportError instanceof Error
          ? remoteTransportError.message
          : String(remoteTransportError)) || 'Remote tool execution failed'
      : null;
    const remoteResult =
      remoteOutcome && 'result' in remoteOutcome ? remoteOutcome.result : undefined;

    // If only local tools, return the single/first result unwrapped
    if (remoteIndices.length === 0 && localResults.length === 1) {
      return localResults[0].result;
    }

    // Merge results into the backend's results[] format.
    const remoteData = (
      remoteResult?.data &&
      typeof remoteResult.data === 'object' &&
      !Array.isArray(remoteResult.data)
        ? remoteResult.data
        : {}
    ) as Record<string, unknown>;
    const remoteResults = remoteErrorMessage
      ? remoteIndices.map(index => ({
          response: { successful: false, data: {}, error: remoteErrorMessage },
          tool_slug: parsed[index].tool_slug,
          error: remoteErrorMessage,
        }))
      : ((Array.isArray(remoteData.results) ? remoteData.results : []) as Array<
          Record<string, unknown>
        >);

    // Build local result entries matching backend format
    const localEntries = localResults.map(({ index, result }) => ({
      response: {
        successful: result.successful,
        data: result.data,
        ...(result.error ? { error: result.error } : {}),
      },
      tool_slug: parsed[index].tool_slug,
      index,
      ...(result.error ? { error: result.error } : {}),
    }));

    // Restore original request order, then re-index sequentially so there are no collisions.
    const merged: Array<Record<string, unknown>> = [
      ...remoteResults.map((entry, remotePosition) => ({
        ...entry,
        index: remoteIndices[remotePosition] ?? remotePosition,
      })),
      ...localEntries,
    ].sort((a, b) => Number(a.index) - Number(b.index));
    const allResults = merged.map((entry, i): Record<string, unknown> => ({
      ...entry,
      index: i,
    }));
    const failedCount = allResults.filter(r => r.error).length;
    const mergedData: Record<string, unknown> = {
      ...remoteData,
      results: allResults,
    };
    if (
      localEntries.length > 0 &&
      (remoteErrorMessage ||
        ['total_count', 'success_count', 'error_count'].some(key => key in remoteData))
    ) {
      mergedData.total_count = allResults.length;
      mergedData.success_count = allResults.length - failedCount;
      mergedData.error_count = failedCount;
    }
    const remoteError =
      remoteErrorMessage ?? (typeof remoteResult?.error === 'string' ? remoteResult.error : null);
    const hasAnyError = localResults.some(r => r.result.error) || !!remoteError;

    return {
      data: mergedData,
      error: hasAnyError
        ? remoteError && failedCount === 0
          ? remoteError
          : `${failedCount} out of ${allResults.length} tools failed`
        : null,
      successful: !hasAnyError,
    };
  }
}