@eventcatalog/core 3.40.1 → 3.41.0

package/eventcatalog/src/stores/sidebar-store/builders/agent.ts

@@ -0,0 +1,141 @@
+import type { CollectionEntry } from 'astro:content';
+import { buildUrl } from '@utils/url-builder';
+import type { NavNode, ChildRef, ResourceGroupContext } from './shared';
+import {
+  uniqueBy,
+  buildQuickReferenceSection,
+  buildOwnersSection,
+  shouldRenderSideBarSection,
+  buildResourceGroupSections,
+  buildRepositorySection,
+  buildAttachmentsSection,
+  buildDiagramNavItems,
+  buildResourceDocsSection,
+} from './shared';
+import { isChangelogEnabled } from '@utils/feature';
+import { isVisualiserEnabled } from '@utils/feature';
+import { pluralizeMessageType } from '@utils/collections/messages';
+import { iconFieldsForResource } from '@utils/icon';
+
+const uniqueRefs = (refs: string[]) => [...new Set(refs)];
+
+export const buildAgentNode = (
+  agent: CollectionEntry<'agents'>,
+  owners: any[],
+  context: ResourceGroupContext,
+  agentChannels: CollectionEntry<'channels'>[] = [],
+  flowRefs: string[] = []
+): NavNode => {
+  const sendsMessages = agent.data.sends || [];
+  const receivesMessages = agent.data.receives || [];
+
+  const dataStoresInAgent = uniqueBy([...(agent.data.writesTo || []), ...(agent.data.readsFrom || [])], 'id');
+
+  const agentFlows = agent.data.flows || [];
+  const agentFlowRefs = uniqueRefs([
+    ...agentFlows.map((flow) => `flow:${(flow as any).data.id}:${(flow as any).data.version}`),
+    ...flowRefs,
+  ]);
+  const hasFlows = agentFlowRefs.length > 0;
+
+  const hasAttachments = agent.data.attachments && agent.data.attachments.length > 0;
+  const hasDataStores = dataStoresInAgent.length > 0;
+  const resourceGroups = agent.data.resourceGroups || [];
+  const hasResourceGroups = resourceGroups.length > 0;
+
+  const renderResourceGroups = hasResourceGroups && shouldRenderSideBarSection(agent, 'resourceGroups');
+  const renderMessages = shouldRenderSideBarSection(agent, 'messages');
+  const renderVisualiser = isVisualiserEnabled();
+  const renderOwners = owners.length > 0 && shouldRenderSideBarSection(agent, 'owners');
+  const renderRepository = agent.data.repository && shouldRenderSideBarSection(agent, 'repository');
+  const docsSection = buildResourceDocsSection(
+    'agents',
+    agent.data.id,
+    agent.data.version,
+    context.resourceDocs,
+    context.resourceDocCategories
+  );
+
+  const agentDiagrams = agent.data.diagrams || [];
+  const diagramNavItems = buildDiagramNavItems(agentDiagrams, context.diagrams);
+  const hasDiagrams = diagramNavItems.length > 0;
+
+  return {
+    type: 'item',
+    title: agent.data.name,
+    badge: 'Agent',
+    summary: agent.data.summary,
+    ...iconFieldsForResource(agent.data, 'Bot'),
+    pages: [
+      buildQuickReferenceSection(
+        [
+          { title: 'Overview', href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}`) },
+          isChangelogEnabled() &&
+            shouldRenderSideBarSection(agent, 'changelog') && {
+              title: 'Changelog',
+              href: buildUrl(`/docs/agents/${agent.data.id}/${agent.data.version}/changelog`),
+            },
+        ].filter(Boolean) as { title: string; href: string }[]
+      ),
+      docsSection,
+      renderVisualiser && {
+        type: 'group',
+        title: 'Architecture',
+        icon: 'Workflow',
+        pages: [
+          {
+            type: 'item',
+            title: 'Map',
+            href: buildUrl(`/visualiser/agents/${agent.data.id}/${agent.data.version}`),
+          },
+        ].filter(Boolean) as ChildRef[],
+      },
+      hasDiagrams && {
+        type: 'group',
+        title: 'Diagrams',
+        icon: 'FileImage',
+        pages: diagramNavItems,
+      },
+      renderResourceGroups && buildResourceGroupSections(resourceGroups, context),
+      hasDataStores && {
+        type: 'group',
+        title: 'State and Persistence',
+        icon: 'Database',
+        pages: dataStoresInAgent.map((dataStore) => `container:${(dataStore as any).data.id}:${(dataStore as any).data.version}`),
+      },
+      sendsMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Outbound Messages',
+          icon: 'Mail',
+          pages: sendsMessages.map(
+            (message) => `${pluralizeMessageType(message as any)}:${(message as any).data.id}:${(message as any).data.version}`
+          ),
+        },
+      receivesMessages.length > 0 &&
+        renderMessages && {
+          type: 'group',
+          title: 'Inbound Messages',
+          icon: 'Mail',
+          pages: receivesMessages.map(
+            (receive) => `${pluralizeMessageType(receive as any)}:${(receive as any).data.id}:${(receive as any).data.version}`
+          ),
+        },
+      agentChannels.length > 0 && {
+        type: 'group',
+        title: 'Channels',
+        icon: 'ArrowRightLeft',
+        pages: agentChannels.map((channel) => `channel:${(channel as any).data.id}:${(channel as any).data.version}`),
+      },
+      hasFlows && {
+        type: 'group',
+        title: 'Flows',
+        icon: 'Waypoints',
+        pages: agentFlowRefs,
+      },
+      renderOwners && buildOwnersSection(owners),
+      renderRepository && buildRepositorySection(agent.data.repository as { url: string; language: string }),
+      hasAttachments && buildAttachmentsSection(agent.data.attachments as any[]),
+    ].filter(Boolean) as ChildRef[],
+  };
+};

package/eventcatalog/src/stores/sidebar-store/builders/domain.ts

@@ -16,6 +16,9 @@ import { pluralizeMessageType } from '@utils/collections/messages';
 import { getSpecificationsForDomain } from '@utils/collections/domains';
 
 export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[], context: ResourceGroupContext): NavNode => {
+  const agentsInDomain = domain.data.agents || [];
+  const renderAgents = agentsInDomain.length > 0 && shouldRenderSideBarSection(domain, 'agents');
+
   const allServicesInDomain = domain.data.services || [];
   const servicesInDomain = allServicesInDomain.filter((service) => !(service as any).data?.externalSystem);
   const externalSystemsInDomain = allServicesInDomain.filter((service) => (service as any).data?.externalSystem);
@@ -182,6 +185,12 @@ export const buildDomainNode = (domain: CollectionEntry<'domains'>, owners: any[
         icon: 'Server',
         pages: servicesInDomain.map((service) => `service:${(service as any).data.id}:${(service as any).data.version}`),
       },
+      renderAgents && {
+        type: 'group',
+        title: 'Agents In Domain',
+        icon: 'Bot',
+        pages: agentsInDomain.map((agent) => `agent:${(agent as any).data.id}:${(agent as any).data.version}`),
+      },
       renderExternalSystems && {
         type: 'group',
         title: 'External Integrations',

package/eventcatalog/src/stores/sidebar-store/builders/flow.ts

@@ -54,6 +54,7 @@ export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceG
   const eventMap = createVersionedMap(context.events);
   const commandMap = createVersionedMap(context.commands);
   const queryMap = createVersionedMap(context.queries);
+  const agentMap = createVersionedMap(context.agents || []);
   const serviceMap = createVersionedMap(context.services);
   const flowMap = createVersionedMap(context.flows);
   const containerMap = createVersionedMap(context.containers);
@@ -67,6 +68,18 @@ export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceG
       .filter(Boolean)
       .map((service) => `service:${service!.data.id}:${service!.data.version}`)
   );
+  const agentRefs = uniqueRefs(
+    steps
+      .map((step: any) => {
+        const hydratedAgent = Array.isArray(step.agent) ? step.agent[0] : undefined;
+        if (hydratedAgent?.collection && hydratedAgent?.data) return hydratedAgent;
+
+        const pointer = Array.isArray(step.agent) ? undefined : step.agent;
+        return pointer ? resolvePointer(agentMap, pointer) : undefined;
+      })
+      .filter(Boolean)
+      .map((agent) => `agent:${agent!.data.id}:${agent!.data.version}`)
+  );
   const flowRefs = uniqueRefs(
     steps
       .map((step) => (step.flow ? resolvePointer(flowMap, step.flow) : undefined))
@@ -140,6 +153,12 @@ export const buildFlowNode = (flow: CollectionEntry<'flows'>, context: ResourceG
         icon: 'Server',
         pages: serviceRefs,
       },
+      agentRefs.length > 0 && {
+        type: 'group',
+        title: 'Agents',
+        icon: 'Bot',
+        pages: agentRefs,
+      },
       flowRefs.length > 0 && {
         type: 'group',
         title: 'Subflows',

package/eventcatalog/src/stores/sidebar-store/builders/message.ts

@@ -13,6 +13,12 @@ import {
 } from './shared';
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { iconFieldsForResource } from '@utils/icon';
+import { collectionToResourceMap } from '@utils/collections/util';
+
+const getProducerConsumerPageRef = (resource: any) => {
+  const resourceType = collectionToResourceMap[resource.collection as keyof typeof collectionToResourceMap];
+  return `${resourceType}:${resource.data.id}:${resource.data.version}`;
+};
 
 export const buildMessageNode = (
   message: CollectionEntry<'events' | 'commands' | 'queries'>,
@@ -124,14 +130,14 @@ export const buildMessageNode = (
         type: 'group',
         title: 'Producers',
         icon: 'Server',
-        pages: producers.map((producer) => `service:${(producer as any).data.id}:${(producer as any).data.version}`),
+        pages: producers.map(getProducerConsumerPageRef),
         visible: producers.length > 0,
       },
       renderConsumers && {
         type: 'group',
         title: 'Consumers',
         icon: 'Server',
-        pages: consumers.map((consumer) => `service:${(consumer as any).data.id}:${(consumer as any).data.version}`),
+        pages: consumers.map(getProducerConsumerPageRef),
         visible: consumers.length > 0,
       },
       renderFlows && {

package/eventcatalog/src/stores/sidebar-store/builders/shared.ts

@@ -54,6 +54,7 @@ export const uniqueBy = <T>(array: T[], key: keyof T): T[] => {
 };
 
 export type ResourceGroupContext = {
+  agents?: CollectionEntry<'agents'>[];
   services: CollectionEntry<'services'>[];
   domains: CollectionEntry<'domains'>[];
   events: CollectionEntry<'events'>[];
@@ -210,14 +211,16 @@ const buildResourceGroupSection = (resourceGroup: ResourceGroup, context: Resour
   // If no version is provided, we need to get the latest version
   const resourcesWithVersions = resourcesWithTypes.map((item) => {
     let collection: any[] = [];
+    const itemType = item.type as string;
 
-    if (item.type === 'service') collection = context.services;
-    else if (item.type === 'domain') collection = context.domains;
-    else if (item.type === 'event') collection = context.events;
-    else if (item.type === 'command') collection = context.commands;
-    else if (item.type === 'query') collection = context.queries;
-    else if (item.type === 'flow') collection = context.flows;
-    else if (item.type === 'container') collection = context.containers;
+    if (itemType === 'agent') collection = context.agents || [];
+    else if (itemType === 'service') collection = context.services;
+    else if (itemType === 'domain') collection = context.domains;
+    else if (itemType === 'event') collection = context.events;
+    else if (itemType === 'command') collection = context.commands;
+    else if (itemType === 'query') collection = context.queries;
+    else if (itemType === 'flow') collection = context.flows;
+    else if (itemType === 'container') collection = context.containers;
 
     if (item.version === undefined || item.version === 'latest') {
       return { ...item, version: getLatestVersionInCollectionById(collection, item.id as string) };

package/eventcatalog/src/stores/sidebar-store/state.ts

@@ -1,5 +1,6 @@
 import { getCollection } from 'astro:content';
 import type { CollectionEntry } from 'astro:content';
+import { getAgents } from '@utils/collections/agents';
 import { getContainers } from '@utils/collections/containers';
 import { getDomains } from '@utils/collections/domains';
 import { getServices } from '@utils/collections/services';
@@ -14,6 +15,7 @@ import { getEntities } from '@utils/collections/entities';
 import { getResourceDocCategories, getResourceDocs } from '@utils/collections/resource-docs';
 import { buildUrl } from '@utils/url-builder';
 import type { NavigationData, NavNode, ChildRef } from './builders/shared';
+import { buildAgentNode } from './builders/agent';
 import { buildDomainNode } from './builders/domain';
 import { buildServiceNode } from './builders/service';
 import { buildMessageNode } from './builders/message';
@@ -34,6 +36,7 @@ const CACHE_ENABLED = process.env.DISABLE_EVENTCATALOG_CACHE !== 'true';
 let memoryCache: NavigationData | null = null;
 
 type MessageEntry = CollectionEntry<'events' | 'commands' | 'queries'>;
+type AgentEntry = CollectionEntry<'agents'>;
 type ServiceEntry = CollectionEntry<'services'>;
 type ContainerEntry = CollectionEntry<'containers'>;
 type DataProductEntry = CollectionEntry<'data-products'>;
@@ -121,6 +124,42 @@ const buildFlowReferencesByService = ({
   return flowRefsByService;
 };
 
+const buildFlowReferencesByAgent = ({
+  flows,
+  agents,
+}: {
+  flows: CollectionEntry<'flows'>[];
+  agents: CollectionEntry<'agents'>[];
+}) => {
+  const agentMap = createVersionedMap(agents);
+  const flowRefsByAgent = new Map<string, string[]>();
+
+  const addFlowRef = (agent: AgentEntry, flow: CollectionEntry<'flows'>) => {
+    const agentKey = `agent:${agent.data.id}:${agent.data.version}`;
+    const flowKey = `flow:${flow.data.id}:${flow.data.version}`;
+    flowRefsByAgent.set(agentKey, uniqueRefs([...(flowRefsByAgent.get(agentKey) || []), flowKey]));
+  };
+
+  for (const flow of flows) {
+    for (const step of flow.data.steps || []) {
+      if (!(step as any).agent) continue;
+
+      const hydratedAgent = Array.isArray((step as any).agent) ? (step as any).agent[0] : undefined;
+      if (hydratedAgent?.collection && hydratedAgent?.data) {
+        addFlowRef(hydratedAgent as AgentEntry, flow);
+        continue;
+      }
+
+      if (Array.isArray((step as any).agent)) continue;
+
+      const agent = findInMap(agentMap, (step as any).agent.id, (step as any).agent.version);
+      if (agent) addFlowRef(agent, flow);
+    }
+  }
+
+  return flowRefsByAgent;
+};
+
 const buildFlowReferencesByContainer = ({
   flows,
   containers,
@@ -203,6 +242,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
 
   const [
     domains,
+    agents,
     services,
     { events, commands, queries },
     containers,
@@ -218,6 +258,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     resourceDocCategories,
   ] = await Promise.all([
     getDomains({ getAllVersions: false, includeServicesInSubdomains: false }),
+    getAgents({ getAllVersions: false }),
     getServices({ getAllVersions: false }),
     getMessages({ getAllVersions: false }),
     getContainers({ getAllVersions: false }),
@@ -240,6 +281,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const messages = [...events, ...commands, ...queries];
 
   const context = {
+    agents,
     services,
     domains,
     events,
@@ -268,6 +310,15 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     })
   );
 
+  const agentsWithOwners = await Promise.all(
+    agents.map(async (agent) => {
+      const ownersInAgent = agent.data.owners || [];
+      const owners = await Promise.all(ownersInAgent.map((owner) => getOwner(owner)));
+      const filteredOwners = owners.filter((o) => o !== undefined) as Array<NonNullable<(typeof owners)[0]>>;
+      return { agent, owners: filteredOwners };
+    })
+  );
+
   // Services with owners
   const servicesWithOwners = await Promise.all(
     services.map(async (service) => {
@@ -318,6 +369,8 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     {} as Record<string, NavNode | string>
   );
 
+  const rawAgents = await getCollection('agents');
+
   // Compute channels for each service from raw sends[].to / receives[].from pointers
   const rawServices = await getCollection('services');
   const channelMap = createVersionedMap(channels);
@@ -354,8 +407,55 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     }
   }
 
+  const agentChannelsMap = new Map<string, CollectionEntry<'channels'>[]>();
+
+  for (const agent of agents) {
+    const rawAgent = rawAgents.find((a) => a.data.id === agent.data.id && a.data.version === agent.data.version);
+    if (!rawAgent) continue;
+
+    const pointers: Array<{ id: string; version?: string }> = [];
+    for (const send of rawAgent.data.sends ?? []) {
+      for (const ch of send.to ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+    for (const receive of rawAgent.data.receives ?? []) {
+      for (const ch of receive.from ?? []) {
+        pointers.push({ id: ch.id, version: ch.version });
+      }
+    }
+
+    const seen = new Set<string>();
+    const resolved: CollectionEntry<'channels'>[] = [];
+    for (const pointer of pointers) {
+      const key = `${pointer.id}-${pointer.version ?? 'latest'}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const match = findInMap(channelMap, pointer.id, pointer.version);
+      if (match) resolved.push(match as CollectionEntry<'channels'>);
+    }
+
+    if (resolved.length > 0) {
+      agentChannelsMap.set(`${agent.data.id}:${agent.data.version}`, resolved);
+    }
+  }
+
+  const flowRefsByAgent = buildFlowReferencesByAgent({ flows, agents });
   const flowRefsByService = buildFlowReferencesByService({ flows, services });
 
+  const agentNodes = agentsWithOwners.reduce(
+    (acc, { agent, owners }) => {
+      const versionedKey = `agent:${agent.data.id}:${agent.data.version}`;
+      const agentChannels = agentChannelsMap.get(`${agent.data.id}:${agent.data.version}`) || [];
+      acc[versionedKey] = buildAgentNode(agent, owners, context, agentChannels, flowRefsByAgent.get(versionedKey) || []);
+      if (agent.data.latestVersion === agent.data.version) {
+        acc[`agent:${agent.data.id}`] = versionedKey;
+      }
+      return acc;
+    },
+    {} as Record<string, NavNode | string>
+  );
+
   const serviceNodes = servicesWithOwners.reduce(
     (acc, { service, owners }) => {
       const versionedKey = `service:${service.data.id}:${service.data.version}`;
@@ -370,10 +470,18 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     {} as Record<string, NavNode | string>
   );
 
-  // Build a set of message IDs that have field usage declared by any service.
-  // We use rawServices (from getCollection) because the hydrated services replace
+  // Build a set of message IDs that have field usage declared by any service or agent.
+  // We use raw collections because the hydrated resources replace
   // sends/receives pointers with resolved message entries, which strips the fields property.
   const messagesWithFieldUsage = new Set<string>();
+  for (const agent of rawAgents) {
+    for (const pointer of agent.data.sends || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+    for (const pointer of agent.data.receives || []) {
+      if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
+    }
+  }
   for (const service of rawServices) {
     for (const pointer of service.data.sends || []) {
       if (pointer.fields?.length) messagesWithFieldUsage.add(pointer.id);
@@ -572,6 +680,13 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
     pages: domains.map((domain) => `domain:${domain.data.id}:${domain.data.version}`),
   });
 
+  const agentsList = createLeaf(agents, {
+    type: 'item',
+    title: 'Agents',
+    icon: 'Bot',
+    pages: agents.map((agent) => `agent:${agent.data.id}:${agent.data.version}`),
+  });
+
   const internalServices = services.filter((service) => !service.data.externalSystem);
   const externalServices = services.filter((service) => service.data.externalSystem);
 
@@ -695,6 +810,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const allChildrenKeys = [
     'list:domains',
     'list:services',
+    'list:agents',
     'list:external-systems',
     'list:messages',
     'list:channels',
@@ -708,6 +824,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const allChildrenNodes = [
     domainsList,
     servicesList,
+    agentsList,
     externalSystemsList,
     messagesList,
     channelList,
@@ -734,6 +851,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const allNodes: Record<string, NavNode> = {
     ...(domainsList ? { 'list:domains': domainsList } : {}),
     ...(servicesList ? { 'list:services': servicesList } : {}),
+    ...(agentsList ? { 'list:agents': agentsList } : {}),
     ...(externalSystemsList ? { 'list:external-systems': externalSystemsList } : {}),
     ...(eventsList ? { 'list:events': eventsList } : {}),
     ...(commandsList ? { 'list:commands': commandsList } : {}),
@@ -773,6 +891,7 @@ export const getNestedSideBarData = async (): Promise<NavigationData> => {
   const allGeneratedNodes = {
     ...rootDomainsNodes,
     ...domainNodes,
+    ...agentNodes,
     ...serviceNodes,
     ...messageNodes,
     ...channelNodes,

package/eventcatalog/src/types/index.ts

@@ -1,4 +1,5 @@
 export type CollectionTypes =
+  | 'agents'
   | 'commands'
   | 'events'
   | 'queries'
@@ -11,8 +12,9 @@ export type CollectionTypes =
   | 'diagrams'
   | 'data-products';
 export type CollectionMessageTypes = 'commands' | 'events' | 'queries';
-export type CollectionUserTypes = 'users';
+export type CollectionUserTypes = 'users' | 'teams';
 export type PageTypes =
+  | 'agents'
   | 'events'
   | 'commands'
   | 'queries'

package/eventcatalog/src/utils/collection-colors.ts

@@ -9,6 +9,7 @@ export type CollectionColor =
   | 'red'
   | 'gray'
   | 'cyan'
+  | 'sky'
   | 'indigo';
 
 export const getColorForCollection = (collection: string): CollectionColor => {
@@ -33,6 +34,8 @@ export const getColorForCollection = (collection: string): CollectionColor => {
       return 'purple';
     case 'domains':
       return 'yellow';
+    case 'agents':
+      return 'sky';
     case 'services':
       return 'pink';
     case 'data-products':
@@ -55,6 +58,7 @@ export const tailwind500RgbByColor: Record<CollectionColor, string> = {
   red: '239 68 68',
   gray: '107 114 128',
   cyan: '6 182 212',
+  sky: '14 165 233',
   indigo: '99 102 241',
 };
 
@@ -69,6 +73,7 @@ export const collectionTextColorClassByColor: Record<CollectionColor, string> =
   red: 'text-red-500',
   gray: 'text-gray-500',
   cyan: 'text-cyan-500',
+  sky: 'text-sky-500',
   indigo: 'text-indigo-500',
 };