Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

22.9 KB
Raw Blame
import { logger } from '@librechat/data-schemas';
import {
  ResourceType,
  PermissionBits,
  EModelEndpoint,
  MAX_SUBAGENT_GRAPH_NODES,
} from 'librechat-data-provider';
import type {
  Agent,
  GraphEdge,
  TModelsConfig,
  TEndpointOption,
  AgentSubagentGraph,
} from 'librechat-data-provider';
import type { Response as ServerResponse } from 'express';
import type {
  InitializedAgent,
  InitializeAgentParams,
  InitializeAgentDbMethods,
} from './initialize';
import type { ValidateAgentModelParams } from './validation';
import type { ServerRequest } from '~/types';
import { validateAgentModel as defaultValidateAgentModel } from './validation';
import { initializeAgent as defaultInitializeAgent } from './initialize';
import { createEdgeCollector, resolveReachableGraph } from './edges';
import { isFatalAgentInitializationError } from './errors';
import { createConcurrencyLimiter } from '~/utils/promise';
import { getLookupConcurrency } from '~/utils/concurrency';
import { createSequentialChainEdges } from './chain';
import { detachOnAbort } from '~/utils/promises';

const SUBAGENT_GRAPH_LOAD_CONCURRENCY = 4;

/**
 * Callback invoked after a sub-agent is successfully initialized.
 * Used by callers that need to track per-agent tool context (e.g., for
 * the ON_TOOL_EXECUTE event handler closure).
 */
export type OnAgentInitializedCallback = (
  agentId: string,
  agent: Agent,
  config: InitializedAgent,
) => void;

/**
 * Minimal permission check signature used to verify VIEW access on a
 * candidate sub-agent before it is loaded into the run.
 */
export type CheckAgentPermission = (params: {
  userId: string;
  role?: string;
  resourceType: string;
  resourceId: unknown;
  requiredPermission: number;
}) => Promise<boolean>;

export interface DiscoverConnectedAgentsParams {
  req: ServerRequest;
  res: ServerResponse;
  /** Owning run signal used to distinguish cancellation from dependency aborts. */
  signal?: AbortSignal;
  /** The already-initialized primary agent config (starting point for BFS). */
  primaryConfig: InitializedAgent;
  /**
   * Optional legacy chain: agent IDs to append as sequential direct edges.
   * Used by the deprecated Agent Chain feature.
   */
  agent_ids?: string[];
  endpointOption?: Partial<TEndpointOption>;
  allowedProviders: Set<string>;
  modelsConfig: TModelsConfig;
  loadTools: InitializeAgentParams['loadTools'];
  requestFiles?: InitializeAgentParams['requestFiles'];
  conversationId?: string | null;
  parentMessageId?: string | null;
  /** Normalized runtime request metadata forwarded to MCP tool loading. */
  requestBody?: InitializeAgentParams['requestBody'];
  /**
   * ResourceType to check each sub-agent's access against. Defaults to
   * `AGENT` for the in-app chat flow. Callers whose entry-point gates on
   * a different resource type (e.g. the OpenAI-compat controllers gate on
   * `REMOTE_AGENT`) must pass the matching resource type so sub-agents
   * don't bypass the same sharing boundary enforced at the route.
   */
  resourceType?: string;
  /**
   * Optional per-sub-agent skill scoper. When provided, its return value
   * is forwarded to `initializeAgent` as `accessibleSkillIds` so each
   * handoff agent sees only the skills that match its own `skills`
   * allowlist (or the full accessible set when scoping is disabled).
   */
  computeAccessibleSkillIds?: (agent: Agent) => InitializeAgentParams['accessibleSkillIds'];
  /** Optional per-sub-agent skill authoring gate, paired with the scoped skill IDs. */
  computeSkillAuthoringAvailable?: (
    agent: Agent,
    accessibleSkillIds: InitializeAgentParams['accessibleSkillIds'],
  ) => InitializeAgentParams['skillAuthoringAvailable'];
  /** Per-user skill active/inactive state, forwarded to each sub-agent. */
  skillStates?: InitializeAgentParams['skillStates'];
  /** Default active-on-share flag, forwarded to each sub-agent. */
  defaultActiveOnShare?: InitializeAgentParams['defaultActiveOnShare'];
  /**
   * Whether the `execute_code` capability is enabled for the run. Forwarded
   * verbatim to each handoff sub-agent so `registerCodeExecutionTools` can
   * expand `agent.tools: ['execute_code']` into the `bash_tool` + `read_file`
   * pair. Omitted (or `undefined`) → the expansion is skipped, matching the
   * primary-agent gate; callers that already resolved the capability set
   * for the primary SHOULD forward the same value here or sub-agents lose
   * code-execution tooling even though their parent had it.
   */
  codeEnvAvailable?: InitializeAgentParams['codeEnvAvailable'];
  /**
   * Sibling of `codeEnvAvailable` for the other role-gated tool — the
   * `file_search` capability AND the caller's `FILE_SEARCH` grant. Forwarded
   * verbatim so a handoff agent re-hydrates prior-turn search files on exactly
   * the terms its parent did.
   */
  fileSearchAvailable?: InitializeAgentParams['fileSearchAvailable'];
  /**
   * The caller's `WEB_SEARCH` grant resolver, forwarded so a handoff or subagent
   * whose provider config turns native web search on is authorized by the same
   * request-memoized read as its parent.
   */
  resolveWebSearchGrant?: InitializeAgentParams['resolveWebSearchGrant'];
  /**
   * Resolves a handoff/subagent's own `instructionsPrompt` link, forwarded so
   * every discovered agent honors its link the same way the primary does.
   * There is no default resolution path, unlike `resolveWebSearchGrant` —
   * omitting it leaves a linked handoff agent with empty instructions.
   */
  resolveLinkedInstructions?: InitializeAgentParams['resolveLinkedInstructions'];
  /** Forwarded verbatim; the resume path sets this `false` for every discovered agent. */
  recordLinkedPromptUsage?: InitializeAgentParams['recordLinkedPromptUsage'];
  /** Sibling of `codeEnvAvailable` — the `stateful_code_sessions` capability flag, forwarded to every handoff `initializeAgent`. */
  statefulSessionsAvailable?: InitializeAgentParams['statefulSessionsAvailable'];
  /** Deployment policy for stateful workspace scopes, forwarded unchanged to every referenced agent. */
  allowedStatefulCodeEnvironments?: InitializeAgentParams['allowedStatefulCodeEnvironments'];
  memoryAvailable?: InitializeAgentParams['memoryAvailable'];
  /**
   * Explicitly enables the authoritative ChatProject guidance/resources for
   * every discovered handoff and saved graph member. This is intentionally
   * independent of the request marker so remote callers can opt in without
   * broadening unrelated agent initialization.
   */
  useChatProjectContext?: InitializeAgentParams['useChatProjectContext'];
  /**
   * Run-level `run_in_background` capability gate. Forwarded verbatim so a
   * handoff/connected agent's own event-driven tools with
   * `tool_options[tool].run_in_background` (and its background-native code
   * pair) get the injected param + poll tool, matching how the same agent
   * behaves when run as the primary.
   */
  backgroundToolsAvailable?: InitializeAgentParams['backgroundToolsAvailable'];
  /**
   * Run-level `tool_intents` capability gate. Forwarded verbatim so a
   * handoff/connected agent's opted-in tools get the injected `intent` param,
   * matching how the same agent behaves when run as the primary.
   */
  toolIntentsAvailable?: InitializeAgentParams['toolIntentsAvailable'];
}

export interface DiscoverConnectedAgentsDeps {
  /** Fetch an agent by string id from the database. */
  getAgent: (filter: { id: string }) => Promise<Agent | null>;
  /** Permission check (typically a wrapper around PermissionService.checkPermission). */
  checkPermission: CheckAgentPermission;
  /** Violation logger passed through to validateAgentModel. */
  logViolation: ValidateAgentModelParams['logViolation'];
  /** DB methods consumed by initializeAgent for each sub-agent. */
  db: InitializeAgentDbMethods;
  /** Optional callback invoked after each sub-agent is initialized. */
  onAgentInitialized?: OnAgentInitializedCallback;
  /** Optional callback invoked when an agent id is skipped (missing or no access). */
  onAgentSkipped?: (agentId: string) => void;
  /**
   * Optional override for `initializeAgent`. Exists primarily so JS callers
   * can inject their test doubles via `jest.mock('@librechat/api')` — since
   * this module's own direct import would otherwise bypass that mock.
   */
  initializeAgent?: typeof defaultInitializeAgent;
  /** Optional override for `validateAgentModel` (same DI rationale). */
  validateAgentModel?: typeof defaultValidateAgentModel;
}

export interface DiscoverConnectedAgentsResult {
  /** Map of agentId -> initialized config for every discovered sub-agent. */
  agentConfigs: Map<string, InitializedAgent>;
  /** Deduplicated, orphan-filtered edges across the primary and sub-agents. */
  edges: GraphEdge[];
  /** Agent ids that were requested but could not be loaded (missing or no access). */
  skippedAgentIds: Set<string>;
  /** Merged MCP auth map from the primary and all sub-agents. */
  userMCPAuthMap?: Record<string, Record<string, string>>;
}

export type GraphSubagentHostConfig = InitializedAgent & {
  subagentGraphConfigs?: Array<{
    definition: AgentSubagentGraph;
    memberConfigs: InitializedAgent[];
  }>;
};

export interface ResolveSubagentGraphsParams extends DiscoverConnectedAgentsParams {
  /** Top-level primary/handoff configs whose saved graph spawn targets should be resolved. */
  rootConfigs: GraphSubagentHostConfig[];
}

async function initializeReferencedAgent(
  agentId: string,
  params: DiscoverConnectedAgentsParams,
  deps: DiscoverConnectedAgentsDeps,
): Promise<{ agent: Agent; config: InitializedAgent } | null> {
  const agent = await detachOnAbort(deps.getAgent({ id: agentId }), params.signal);
  if (!agent) {
    logger.warn(`[initializeReferencedAgent] Agent ${agentId} not found, skipping`);
    deps.onAgentSkipped?.(agentId);
    return null;
  }

  const userId = params.req.user?.id;
  if (!userId) {
    logger.warn(`[initializeReferencedAgent] No authenticated user, skipping agent ${agentId}`);
    deps.onAgentSkipped?.(agentId);
    return null;
  }

  const hasAccess = await detachOnAbort(
    deps.checkPermission({
      userId,
      role: params.req.user?.role,
      resourceType: params.resourceType ?? ResourceType.AGENT,
      resourceId: agent._id,
      requiredPermission: PermissionBits.VIEW,
    }),
    params.signal,
  );
  if (!hasAccess) {
    logger.warn(`[initializeReferencedAgent] User ${userId} lacks VIEW access to agent ${agentId}`);
    deps.onAgentSkipped?.(agentId);
    return null;
  }

  const validateAgentModel = deps.validateAgentModel ?? defaultValidateAgentModel;
  const validation = await detachOnAbort(
    validateAgentModel({
      req: params.req,
      res: params.res,
      agent,
      modelsConfig: params.modelsConfig,
      logViolation: deps.logViolation,
    }),
    params.signal,
  );
  if (!validation.isValid) {
    throw new Error(validation.error?.message);
  }

  const scopedSkillIds = params.computeAccessibleSkillIds?.(agent);
  const initializeAgent = deps.initializeAgent ?? defaultInitializeAgent;
  const config = await detachOnAbort(
    initializeAgent(
      {
        req: params.req,
        res: params.res,
        agent,
        loadTools: params.loadTools,
        requestFiles: params.requestFiles,
        conversationId: params.conversationId,
        parentMessageId: params.parentMessageId,
        requestBody: params.requestBody,
        endpointOption: {
          ...(params.endpointOption ?? {}),
          endpoint: EModelEndpoint.agents,
        },
        allowedProviders: params.allowedProviders,
        useChatProjectContext: params.useChatProjectContext,
        accessibleSkillIds: scopedSkillIds,
        skillAuthoringAvailable: params.computeSkillAuthoringAvailable?.(agent, scopedSkillIds),
        skillStates: params.skillStates,
        defaultActiveOnShare: params.defaultActiveOnShare,
        codeEnvAvailable: params.codeEnvAvailable,
        fileSearchAvailable: params.fileSearchAvailable,
        resolveWebSearchGrant: params.resolveWebSearchGrant,
        resolveLinkedInstructions: params.resolveLinkedInstructions,
        recordLinkedPromptUsage: params.recordLinkedPromptUsage,
        backgroundToolsAvailable: params.backgroundToolsAvailable,
        toolIntentsAvailable: params.toolIntentsAvailable,
        statefulSessionsAvailable: params.statefulSessionsAvailable,
        allowedStatefulCodeEnvironments: params.allowedStatefulCodeEnvironments,
        memoryAvailable: params.memoryAvailable,
        signal: params.signal,
      },
      deps.db,
    ),
    params.signal,
  );
  deps.onAgentInitialized?.(agentId, agent, config);
  return { agent, config };
}

/** Resolves saved graph spawn targets without promoting graph-only members to top-level nodes. */
export async function resolveSubagentGraphs(
  params: ResolveSubagentGraphsParams,
  deps: DiscoverConnectedAgentsDeps,
): Promise<Record<string, Record<string, string>> | undefined> {
  const configById = new Map(params.rootConfigs.map((config) => [config.id, config]));
  const attemptedGraphMemberIds = new Set<string>();
  const failedMemberIds = new Set<string>();
  const loadGraphMember = createConcurrencyLimiter(SUBAGENT_GRAPH_LOAD_CONCURRENCY);
  let userMCPAuthMap: Record<string, Record<string, string>> | undefined;
  for (const config of params.rootConfigs) {
    if (config.userMCPAuthMap) {
      userMCPAuthMap = { ...userMCPAuthMap, ...config.userMCPAuthMap };
    }
  }

  for (const rootConfig of params.rootConfigs) {
    const resolvedGraphs: NonNullable<GraphSubagentHostConfig['subagentGraphConfigs']> = [];
    for (const definition of rootConfig.subagents?.enabled === true
      ? (rootConfig.subagents.graphs ?? [])
      : []) {
      const memberIds = [...new Set(definition.agent_ids)];
      const newMemberIds = memberIds.filter(
        (memberId) => !configById.has(memberId) && !attemptedGraphMemberIds.has(memberId),
      );
      if (attemptedGraphMemberIds.size + newMemberIds.length > MAX_SUBAGENT_GRAPH_NODES) {
        logger.warn('[resolveSubagentGraphs] Subagent graph node limit exceeded', {
          parentAgentId: rootConfig.id,
          graphType: definition.type,
          loadedSubagentCount: attemptedGraphMemberIds.size,
          stagedSubagentCount: newMemberIds.length,
          maxSubagentGraphNodes: MAX_SUBAGENT_GRAPH_NODES,
        });
        continue;
      }
      for (const memberId of newMemberIds) {
        attemptedGraphMemberIds.add(memberId);
      }

      const resolvedMembers = await Promise.all(
        memberIds.map((memberId) => {
          const existing = configById.get(memberId);
          if (existing) {
            return Promise.resolve({ config: existing });
          }
          if (failedMemberIds.has(memberId)) {
            return Promise.resolve(null);
          }
          return loadGraphMember(async () => {
            try {
              const resolved = await initializeReferencedAgent(memberId, params, {
                ...deps,
                onAgentInitialized: undefined,
              });
              if (!resolved) {
                failedMemberIds.add(memberId);
              }
              return resolved;
            } catch (error) {
              if (isFatalAgentInitializationError(error, { signal: params.signal })) {
                throw error;
              }
              failedMemberIds.add(memberId);
              logger.error(
                `[resolveSubagentGraphs] Error processing graph member ${memberId}:`,
                error,
              );
              deps.onAgentSkipped?.(memberId);
              return null;
            }
          });
        }),
      );
      for (let index = 0; index < memberIds.length; index++) {
        const resolvedMember = resolvedMembers[index];
        if (!resolvedMember) {
          continue;
        }
        const memberId = memberIds[index];
        configById.set(memberId, resolvedMember.config);
        if (resolvedMember.config.userMCPAuthMap) {
          userMCPAuthMap = {
            ...userMCPAuthMap,
            ...resolvedMember.config.userMCPAuthMap,
          };
        }
        if ('agent' in resolvedMember) {
          deps.onAgentInitialized?.(memberId, resolvedMember.agent, resolvedMember.config);
        }
      }
      if (resolvedMembers.some((member) => member == null)) {
        logger.warn('[resolveSubagentGraphs] Skipping incomplete graph subagent', {
          parentAgentId: rootConfig.id,
          graphType: definition.type,
          expectedMemberCount: memberIds.length,
          resolvedMemberCount: resolvedMembers.filter(Boolean).length,
        });
        continue;
      }
      const memberConfigs: InitializedAgent[] = [];
      for (let index = 0; index < memberIds.length; index++) {
        const resolvedMember = resolvedMembers[index] as {
          config: InitializedAgent;
        };
        memberConfigs.push(resolvedMember.config);
      }
      resolvedGraphs.push({
        definition,
        memberConfigs,
      });
    }
    rootConfig.subagentGraphConfigs = resolvedGraphs;
  }
  return userMCPAuthMap;
}

/**
 * Discovers and initializes all agents reachable from `primaryConfig.edges`
 * via BFS. This is the shared graph-topology discovery logic that enables
 * multi-agent handoffs (A -> B -> C) in both the primary chat flow and the
 * OpenAI-compatible / Responses API controllers.
 *
 * Skips agents the caller cannot load (missing from DB or lacking VIEW
 * permission) and filters out orphaned edges so `createRun` never sees an
 * edge pointing at a missing node — which would otherwise trigger a
 * `Found edge ending at unknown node` validation error from StateGraph.
 */
export async function discoverConnectedAgents(
  params: DiscoverConnectedAgentsParams,
  deps: DiscoverConnectedAgentsDeps,
): Promise<DiscoverConnectedAgentsResult> {
  const { primaryConfig, agent_ids } = params;
  const { onAgentSkipped } = deps;

  const agentConfigs = new Map<string, InitializedAgent>();
  const skippedAgentIds = new Set<string>();
  // Shallow-clone so the sub-agent merges below don't silently mutate
  // `primaryConfig.userMCPAuthMap` on the caller's object.
  let userMCPAuthMap: Record<string, Record<string, string>> | undefined =
    primaryConfig.userMCPAuthMap ? { ...primaryConfig.userMCPAuthMap } : undefined;

  const markSkipped = (agentId: string): void => {
    skippedAgentIds.add(agentId);
    onAgentSkipped?.(agentId);
  };

  const loadAgent = (agentId: string): ReturnType<typeof initializeReferencedAgent> =>
    initializeReferencedAgent(agentId, params, {
      ...deps,
      onAgentSkipped: markSkipped,
    });

  /** Side effects are applied in discovery order so merges stay deterministic. */
  const applyLoaded = (
    agentId: string,
    loaded: Awaited<ReturnType<typeof initializeReferencedAgent>>,
  ): Agent | null => {
    if (!loaded) {
      return null;
    }
    const { agent, config } = loaded;

    if (userMCPAuthMap != null) {
      Object.assign(userMCPAuthMap, config.userMCPAuthMap ?? {});
    } else if (config.userMCPAuthMap) {
      // Clone so subsequent sub-agent merges don't mutate the first
      // sub-agent's own `config.userMCPAuthMap` in place — symmetric with
      // the shallow clone applied to the primary's map above.
      userMCPAuthMap = { ...config.userMCPAuthMap };
    }

    agentConfigs.set(agentId, config);
    return agent;
  };

  const processAgent = async (agentId: string): Promise<Agent | null> =>
    applyLoaded(agentId, await loadAgent(agentId));

  const checkAgentInit = (agentId: string): boolean =>
    agentId === primaryConfig.id || agentConfigs.has(agentId);

  const { edgeMap, agentsToProcess, collectEdges } = createEdgeCollector(
    checkAgentInit,
    skippedAgentIds,
  );

  collectEdges(primaryConfig.edges);

  const loadDiscovered = createConcurrencyLimiter(
    getLookupConcurrency(params.req.config, 'connectedAgentLoads'),
  );
  while (agentsToProcess.size > 0) {
    /** One BFS level: agents already queued are independent, so load them together
     *  and fold results back in queue order. Edges they expose form the next level. */
    const level = [...agentsToProcess];
    agentsToProcess.clear();
    /** Outcomes never reject; a fatal error also rejects `fatal`, so it surfaces as soon
     *  as it happens instead of after earlier, slower siblings finish. */
    let rejectFatal: (error: unknown) => void = () => undefined;
    const fatal = new Promise<never>((_, reject) => {
      rejectFatal = reject;
    });
    fatal.catch(() => undefined);
    const outcomes = level.map((agentId) =>
      loadDiscovered(async () => {
        try {
          return { loaded: await loadAgent(agentId) };
        } catch (error) {
          if (isFatalAgentInitializationError(error, { signal: params.signal })) {
            rejectFatal(error);
          }
          return { error };
        }
      }),
    );
    /** Stage every loaded config before collecting edges, so a sibling referenced by
     *  another member of the level is not queued a second time. */
    const loadedAgents: Array<Agent | null> = [];
    for (let index = 0; index < level.length; index++) {
      const agentId = level[index];
      const outcome = await Promise.race([outcomes[index], fatal]);
      if ('error' in outcome) {
        if (isFatalAgentInitializationError(outcome.error, { signal: params.signal })) {
          throw outcome.error;
        }
        logger.error(`[discoverConnectedAgents] Error processing agent ${agentId}:`, outcome.error);
        markSkipped(agentId);
        continue;
      }
      loadedAgents.push(applyLoaded(agentId, outcome.loaded));
    }
    for (const agent of loadedAgents) {
      if (agent?.edges?.length) {
        collectEdges(agent.edges);
      }
    }
  }

  /** @deprecated Agent Chain — sequential direct-edge fallback */
  if (agent_ids?.length) {
    for (const agentId of agent_ids) {
      if (checkAgentInit(agentId)) {
        continue;
      }
      try {
        await processAgent(agentId);
      } catch (err) {
        if (isFatalAgentInitializationError(err, { signal: params.signal })) {
          throw err;
        }
        logger.error(`[discoverConnectedAgents] Error processing chain agent ${agentId}:`, err);
        markSkipped(agentId);
      }
    }
    /**
     * `createSequentialChainEdges` is typed against `@librechat/agents`'s
     * `GraphEdge` (which uses `BaseMessage` from `@langchain/core`) whereas
     * `collectEdges` uses the `librechat-data-provider` variant (structural
     * `BaseMessage`). The produced chain edges are structurally identical and
     * only carry `edgeType`, `from`, `to`, `prompt`, `excludeResults` —
     * interchangeable for edge collection purposes.
     */
    const chain = await createSequentialChainEdges([primaryConfig.id].concat(agent_ids), '{convo}');
    collectEdges(chain as unknown as GraphEdge[]);
  }

  const preFilterEdges = Array.from(edgeMap.values());
  const { reachable, edges } = resolveReachableGraph(
    [primaryConfig.id],
    agentConfigs.keys(),
    preFilterEdges,
    skippedAgentIds,
  );

  for (const agentId of [...agentConfigs.keys()]) {
    if (!reachable.has(agentId)) {
      agentConfigs.delete(agentId);
    }
  }

  return {
    agentConfigs,
    edges,
    skippedAgentIds,
    userMCPAuthMap,
  };
}