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.

5.1 KB
Raw Blame
/**
 * @fileoverview Session context implementation injected into custom tool execute functions.
 */
import { Composio as ComposioClient } from '@composio/client';
import type {
  SessionContext,
  CustomToolsMap,
  InlineCustomToolsWirePayload,
} from '../types/customTool.types';
import type {
  SessionProxyExecuteParams,
  ToolRouterSessionExecuteResponse,
  ToolRouterSessionProxyExecuteResponse,
} from '../types/toolRouter.types';
import {
  SessionProxyExecuteParamsSchema,
  ToolRouterSessionExecuteResponseSchema,
} from '../types/toolRouter.types';
import { ValidationError } from '../errors';
import { transformProxyParams } from './proxyParamsTransform';
import {
  assertUnambiguousCustomToolSlug,
  findCustomTool,
  executeCustomTool,
} from './customToolExecution';
import { transformExecuteResponse } from '../utils/transformers/toolRouterResponseTransform';
import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
import { withCancellation } from '../utils/cancellation';

/**
 * Concrete implementation of SessionContext.
 * One instance is created per session (or per multi-execute batch) and shared
 * across all custom tool invocations, including sibling routing.
 *
 * When `customToolsMap` is provided, `execute()` checks local tools first
 * before falling back to the backend API. This allows tool A to call tool B
 * via `session.execute('B', ...)` without hitting the network.
 *
 * @internal Internal implementation detail. Not exported from `@composio/core`
 * and not part of the public API surface — custom tools receive a
 * `SessionContext` instance via their execute function; they never reference
 * this class directly. Excluded from the generated SDK reference.
 */
export class SessionContextImpl implements SessionContext {
  public readonly userId: string;

  /**
   * Per-execution AbortSignal. Never set on the base instance; `executeCustomTool`
   * grafts it onto a per-call `Object.create` child so concurrent executions
   * sharing this context don't observe each other's signal. Declared here (rather
   * than read via a cast) so the contract is explicit.
   */
  public readonly signal?: AbortSignal;

  constructor(
    private readonly client: ComposioClient,
    userId: string,
    private readonly sessionId: string,
    private readonly customToolsMap?: CustomToolsMap,
    private readonly inlineCustomToolsPayload?: InlineCustomToolsWirePayload
  ) {
    this.userId = userId;
  }

  /**
   * Execute any tool from within a custom tool.
   * Routes to sibling local tools in-process when available,
   * otherwise delegates to the backend API.
   *
   * Returns the same response shape as session.execute().
   */
  async execute(
    toolSlug: string,
    arguments_: Record<string, unknown>
  ): Promise<ToolRouterSessionExecuteResponse> {
    const signal = this.signal;
    const requestOptions = signal ? { signal } : undefined;

    const entry = findCustomTool(this.customToolsMap, toolSlug);
    if (entry) {
      const result = await executeCustomTool(entry, arguments_, this, { signal });
      return ToolRouterSessionExecuteResponseSchema.parse({
        data: result.data,
        error: result.error,
        logId: '',
      });
    }
    assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);

    const executeParams: SessionExecuteParams = {
      tool_slug: toolSlug,
      arguments: arguments_,
    };
    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
    );
    return ToolRouterSessionExecuteResponseSchema.parse(transformExecuteResponse(response));
  }

  /**
   * Proxy API calls through Composio's auth layer.
   * The backend resolves the connected account from the toolkit within the session.
   */
  async proxyExecute(
    params: SessionProxyExecuteParams
  ): Promise<ToolRouterSessionProxyExecuteResponse> {
    const validated = SessionProxyExecuteParamsSchema.safeParse(params);
    if (!validated.success) {
      throw new ValidationError('Invalid proxy execute parameters', { cause: validated.error });
    }

    const signal = this.signal;
    const requestOptions = signal ? { signal } : undefined;

    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,
            },
          }
        : {}),
    };
  }
}